PSoC® Creator™ Component Author Guide

Document # 001-42697 Rev. *G

Cypress Semiconductor 198 Champion Court San Jose, CA 95134-1709 Phone (USA): 800.858.1810 Phone (Intnl): 408.943.2600 http://www.cypress.com

© Cypress Semiconductor Corporation, 2007-2010. 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® and CapSense® are registered trademarks, and PSoC Creator™, Programmable System-on-Chip™, and Warp™ 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.

2

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

Contents

1. Introduction
1.1 1.2 1.3 1.4

9
Component Creation Process Overview...................................................................................9 Conventions............................................................................................................................10 References .............................................................................................................................10 Revision History......................................................................................................................11

2. Creating Projects and Components
2.1

13

2.2 2.3

Cypress Component Requirements........................................................................................13 2.1.1 File Names ..................................................................................................................13 2.1.2 Name Considerations..................................................................................................13 2.1.3 File Name Length Limitations......................................................................................13 2.1.4 Component Versioning................................................................................................14 Create a Library Project..........................................................................................................15 Add a New Component Item (Symbol) ...................................................................................16 2.3.1 Create an Empty Symbol ............................................................................................16 2.3.2 Create a Symbol using the Wizard..............................................................................19

3. Defining Symbol Information
3.1

21

3.2 3.3 3.4 3.5 3.6

Parameter Overview ...............................................................................................................21 3.1.1 Formal versus Local Parameters ................................................................................22 3.1.2 Built-In Parameters .....................................................................................................22 3.1.3 Expression Functions..................................................................................................23 3.1.4 User-Defined Types ....................................................................................................24 Define Symbol Parameters.....................................................................................................24 Add Parameter Validators.......................................................................................................26 Add User-Defined Types ........................................................................................................27 Specify Document Properties .................................................................................................28 3.5.1 Define Catalog Placement ..........................................................................................29 Define Format Shape Properties ............................................................................................30 3.6.1 Common Shape Properties.........................................................................................30 3.6.2 Advanced Shape Properties .......................................................................................30

4. Adding an Implementation
4.1

31

4.2

Implement with a Schematic...................................................................................................31 4.1.1 Add a Schematic .........................................................................................................31 4.1.2 Complete the Schematic .............................................................................................32 4.1.2.1 Design-Wide Resources (DWR) Settings....................................................32 Create a Schematic Macro .....................................................................................................32 4.2.1 Add a Schematic Macro Document.............................................................................32 4.2.2 Define the Macro.........................................................................................................34 4.2.3 Versioning ...................................................................................................................34 4.2.4 Component Update Tool .............................................................................................34

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

3

.....................................2.......................................................................................................38 4....................................4 Status Register...........................................4 UDB Array Changes ........59 6.......................................................................................2......................40 4......36 Implement with Verilog .........................61 6.................................................4 Macro File Naming Conventions........3....................................52 5....54 5.....8 When to use Cypress Provided Primitives instead of Logic .....................................................1..................35 4.2 User-Defined Types ...................1 Silicon Revision Definition ..........3................3 4...........4 API Overview................2...............................35 4.7 Macro Datasheets...................................................................50 Implement with Software ....................3 Control Register .................................................................1 API generation ..............................................................................................................................................................................1...................................1 New File ..2...................................53 VCS .............5..............................1 Parameters......................................................................................2 53 ModelSim.............35 4..........................5........1........36 4....................................................5.........................1....................................................1................................................................48 4...........3........................3......................................................c file..1 Component Catalog Placement .......................6.........39 4...37 4..............2 Test Bench Definition .........3 Complete the Verilog file ................9..........................3.......3....2.................................................3.........3....................................1.............................................................................50 4.......62 Complete the ..............................2 Summary Text ...................6 Merge Region ..........9 Example ...................................1...............................3.....3 6.............................2 Datapath(s).....................................2 Component Configuration for Different Silicon Revisions ..............................................................................................................................................2............2......59 6..............................................5 Verilog Hierarchy Subsitution................6 Fixed Blocks ..........................................................................................................60 6..........36 4........................ Document # 001-42697 Rev................50 4...................49 4...................................................................................... Adding API Files 6..............37 4............. Simulating the Hardware 5...9 Warp Features for Component Creation..........................................54 6.........................................................................................5........................................................35 4......................4.................2...................1 59 6..........8 Post-Processing of the Macro......1 Verilog File Requirements...............3......................................62 4 PSoC Creator Component Author Guide.....5..........................................54 5.......................................40 4.........................................2 Add a Verilog File..............................59 6.............38 4........4.............61 Add API Files to a Component .......................................7 Design-Wide Resources .......................................................................................................5 4.......6 Document Properties ........................................................3.......2 File Naming..1 Generate Statements ............................3 API Template Expansion..................35 4....................2 Existing File ....3....50 4.3....1 Macro and Symbol with Same Name ..........................37 4.........................3.........................................5 UDB Elements .................50 4.........3....1...............35 4........................2..4 Conditional API Generation ....................................7 API Cases ...................................47 4...........................................6......1 Tools .....6.....................2.................................................................................................................59 6.............................................3..59 6.......3.............2............................62 Complete the ......3...........2..........................................................................1 Clock/Enable Specification......35 4................................................1....3.3............h file.....................Contents 4.................................................................... *G .........35 4.............................................................41 4..................3..........2 6.......3 Hidden Property .1 5.................................................................................................................................................38 4..............................................................................................................59 6................5 Count7.....................................................5.........................................................2.61 6...................

.............................3..................................72 8.........................................1 Use Distinct Namespaces ......63 7...................5 cystatus CyBtldrCommRead(uint8 *data...4 Passing Parameters ....................................1................................... Customizing Components 7..........................................78 9...................................................8 Firmware Traffic Cop ...........5 Add Resource Files.........................1...64 7......................................................................1........................73 8..........1..............................3 Add Source File(s) .....................................................................5.........................77 9..2...........................1.........1..................1...........................................5.................................................................4 Create Sub-Directories in “Custom” ........69 7.......................................3..................................................................................................................................73 8...........Contents 7.......78 9..........................2 void CyBtldrCommStop(void) ............................................ uint8 timeOut)79 9...........67 7...........................................64 7................... Adding Bootloader Support 9..................................68 7..........1 77 Firmware........................................................................ uint16 size..............2........................2 7..........2.....................1.....................................................................................3 Customizer Bootloader Interface.....9.......................................................................................................5..............2 Functions. uint16 size........2 Customization Interfaces.....66 7...............................................................72 8........1 LaunchTuner API ....................................................5.......67 Interfaces .......................73 8.................2 Communications API (ICyTunerCommAPI_v1) .....65 Usage Guidelines ...................................................................................... uint16 *count..................4 7.............................74 8......................73 8. Adding Tuning Support 8.............77 9.......1....................................1.....................66 7.....................2 Use Distinct External Dependencies............1..1 Protecting Customizer Source .................................................3.......67 7..............................69 7...................1 63 7.................................................................................5...............................71 Architecture....5 Customizers from Source ...............10 A simple tuner.....................................................................................69 7..................... uint8 timeOut)78 9.......74 8....................................................3.....................................5.......................................................... Document # 001-42697 Rev.................7 Specify Assembly References................6 Communication Setup ..................................................................1.1 Guarding .............................77 9...................63 7..3 Use Common Component To Share Code....................3 71 Tuning Framework..........................................................3 Clock Query in Customizers...........................................3 7............3 void CyBtldrCommReset(void) .........................64 7..........................................3...............2 ICyClockDataProvider_v1 ................................................................................................................................................................................................................................1 System Interfaces .....................4 Clock API support .........................1............................................65 7..............66 Customization Examples ..............................................................................................1..................................................1 void CyBtldrCommStart(void) ................75 9.........................................63 7....................................................2........2 8............................. uint16 *count....1.............................................................................................2................................................................................................................1 ICyTerminalQuery_v1.........6 Name the Class / Customizer ..78 9........ *G 5 ................................................................1.............................69 8......................66 7............................................5 Component Tuner DLL .............9 Component Modifications .................4 cystatus CyBtldrCommWrite(uint8 *data..............2 Development flow.....................3...............8 Customizer cache ..........................1 Communication Data..........................................79 PSoC Creator Component Author Guide......74 8..........................................................................1 8..........65 7........................................................................65 Precompiled Component Customizers ......7 Launching the Tuner................3..........................72 Tuning APIs ....72 8.............................................

............................................................1.................1 Add/Create Datasheet ..............3........4............100 11.....3 DMA............. *G .........3................................98 11.....2 Interrupts ............................................103 6 PSoC Creator Component Author Guide......................1............................5 Buffer Overflow .........................................12Negative Clock Edge Hidden Dangers ..2..93 11..............................................................4 UDB to Input/Output Clocking Considerations.............6 Buffer Underflow ......................103 11........3 16-bit Working Register Address Space ..........................4 16-bit Working Register Address Limitation ............3..........................................................4 FIFO Dynamic Control Description .........................4............................................................................7........1...........1....................................103 11.....................................4 Build the project.................3...................97 11.....................................................81 10..........96 11...91 11........9 Utilizing cy_psoc3_udb_clock_enable Primitive ......................................87 11.......................2............................7............................................1..............................................................................................................2 Example .................5 Metastability in Flip-Flops .........1...cystate File.89 11..................87 11.....................................................101 11..........................................................3........1 UDB Architectural Clocking Considerations ...... Finishing the Component 81 10................................................88 11.................................103 11........................85 11..........2 Internal Interrupt Generation and Mask Register..93 11.................Contents 10...............................................88 11.........1 Working Register Address Space .....................................3....................................7 UDB Pair Addressing ........95 11.......1.................2 Design Considerations.............................90 11.......................83 10...................................................3.....99 11.....................................1..............................84 10.....3.................6 Clock Domain Boundary Crossing .......................................................................87 11...................85 10.........3........98 11........................10Utilizing cy_psoc3_sync Component ..........................................3............................89 11..11Routed.....................102 11...................................................................................................................................1 Data Structure Template ...1 Registers for Data Transfer..............6 UDB Local Bus Configuration Interface .................96 11.....................................3 Retention Across Sleep Intervals............................................2......3..................89 11............................................7............3 Add/Create Compatibility XML File..................................... Best Practices 87 11................................................................................1......................................2 Registers for Status ......94 11.........................................................................3.....................8 Synchronous Versus Asynchronous Clocks ........................10Component DMA capabilities .........102 11......4..........................4 Low Power Support ...........100 11.101 11...............................................................3 Spoke width ..........................................................................7.........................2................91 11...........................................................3..........................3 UDB to Chip Resource Clocking Considerations...........................................................82 10...................82 10.......92 11..........84 10.......89 11................2........................2 Add/Create Debug XML File............................1 XML Format .....................92 11..............88 11.......9 DMA Channel Burst Time ......103 11............4 FIFO Status...........................................2...91 11................................ Document # 001-42697 Rev......1......................................3..............................103 11.............................................94 11..........3......................................................................1 Functional requirements ..............................2 Example XML File..........................1 XML Format ................................................................5 Datapath Condition/Data Generation.............3..91 11.....................................................3.....................................................................2 Component Clocking Considerations ..........................................2 8-Bit Working Register Access...................................................................2..............13General Clocking Rules ................................................................99 11........................................1 Clocking............................................................3 Firmware / Application Programming Interface Requirements ........................................ Global and External Clocks .............................1....2...............................7 Long Combinatorial Path Considerations .............................................1 Status Register .................................................................8 DMA Bus Utilization .........................1............................................................................4...1......................................................................................................

..............1 A........................105 11......3 Component Development......4....122 A....... /..............4.............................5.........3........................................1 Bool-ish string................1 Designing for Performance.....119 A..Contents 11........................................................2...................................................................................................................................................................................................................114 11................... unary +..3 String Compare Operators (eq.......................4................5.......6 Casts ....................... <=..................................................3 Optimization .......2.................6........................................................125 A..................................................3...................................................6...123 A.....................................................................6............123 A.............................3...................................... <..........................................6.......5..2......................4 Integers ............................125 A....................126 User-Defined Data Types (Enumerations).......3....124 Operators.5..............3..............6....... Expression Evaluator A.................3 Int-ish strings ..................117 11........ >=)..................................................................3..............................126 String interpolation................6............6........................................1 Arithmetic Operators (+...........1 Datapath ...4.......................122 Data Type Conversion ......................4 Resource choice ...................................5......................... *................................................................................116 11.4.............112 11...112 11...............3 Component Design Considerations .....105 11..........................................124 A............................................................................4..................................................110 11...........................................................................109 11................................2.................................................4..............................................................3........3.........................................126 A...6 Verilog........................................................................................................5 Component Encapsulation...................3................ ge) ..123 A...............................................124 A.........4......5...........1 Resources .........................5.....................................................122 A.......... %.....................6............................................................2..4 Latches ................................................121 Data Types ..2 Case Statements ....................3................................................................ ) ....125 A........................................................................................................... Document # 001-42697 Rev.......................................... !=...........................................5 Reset and Set.......................3............6 Evaluation Contexts................ *G 7 ....................2.................................................................2 121 A..............................................................................6..........................113 11.......3 A......................124 A......5.....................1 Blocking versus Non-Blocking Assignments ...6..............................................3 Float .............3 Float ................5 String ................................5....................6..3 Additions to Enable and Stop Functions...............................2 Error ............1 Bool ..................... lt...........118 11.......................................6......4 Int ......3...................................................................................................5.............121 A......................3.................................................2 Error ......125 A......................109 11................................................4 A..3 Parameter Handling..............................................................................110 11.............................................................................6.... unary -)..............2 Parameterization .....................123 A..4 Testing Components ................................103 11......................119 11............................2........ gt.........4..................116 11..............................................................................104 11.......4.....109 11....................116 11......................................................................2 Numeric Compare Operators (==......3.............1 Hierarchical Design .............................2 Float-ish strings ......121 A......................... ne.........3.... -..5 Ternary Operator ( ?: )....124 A...........3..............................2 Power Management ..........2...........................................................116 11..........................................................................121 A.................................................................................2..........................................................126 PSoC Creator Component Author Guide..................2 PLD Logic ..................5 A.....................112 11.................................... le...125 A................................. >...4 String Concatenation Operator ( ...........112 11........2 Synthesizable Coding Guidelines ..........2.3......................................1 Bool .........................................................................4 Other strings .....................................................5 String .............5........................................2 Save/Restore Methods .........123 A..........................................................2 Designing for Size .....................................111 11.................1 Warp: PSoC Creator Synthesis Tool .........

..1 File Menu........................2 Opening a Verilog File ..........132 B.......................131 B...........2 127 B....................................... *G .........2....3 Copy................................................................................................................4...4............134 8 PSoC Creator Component Author Guide.....2 Adding Parameter to Mask Bit Fields ...................6...........2...2............129 B........129 General tasks .1 B........................................2 Deleting the Datapath Instance........130 B...............................4 Resetting Configuration ......................................................127 Framework.................................3 Bit Field Dependencies ......................5..............129 B...2...................................................................................129 B......................5 B..........................132 B....................2 Edit Menu .........131 B.........................................................6 General Functionality....................128 B.....................................................................2 Menus ..............................................................................................................4 B........ Document # 001-42697 Rev.......................6.....131 B.....4...........................................134 B.....2................................128 B....................2...........................................1 Adding Parameter to Enumerated Bit Fields ...................2..............133 Working with Datapath Instances .......2..........................................................................................................................................................................5.....1 Interface............3....................2 Editing Configuration ............132 Working with Configurations................................................................................................................................133 B..............................................................................................................................130 Working with Bit Field Parameters .............1 Creating a New Datapath Instance .........133 B........................................................................................................................Contents B........................................................................................................3 Saving a File ...........................133 B........133 B.............................. Datapath Configuration Tool B....................4 Help Menu .................. Paste Configuration ........................3 B...........................................................3.......................................1 Launching the Datapath Configuration Tool.................................2............................129 B..............................1 Configuration naming.......................................................................3 View Menu...2....129 B...............3...................6.............129 B...............................................................5.......................3 Setting Initial Register Values .5...

Document # 001-42697 Rev. See references to various chapters in this guide for more information. This chapter includes:     Component Creation Process Overview Conventions References Revision History 1. PSoC Creator Component Author Guide. *G 9 .1. However.1 Component Creation Process Overview The process to create components includes the following high-level steps. Refer also to Chapter 11 for various best practices to follow when creating components. possible workflow process for creating components. but not the only.            Create the library project (Chapter 2) Create a component/symbol (Chapter 2) Define symbol information (Chapter 3) Create the implementation (Chapter 4) Simulate the hardware (Chapter 5) Create API files (Chapter 6) Customize the component (Chapter 7) Add tuning support (advanced) (Chapter 8) Add bootloader support (as needed) (Chapter 9) Add/create documentation and other files/documents (Chapter 10) Build and test the component (Chapter 10) Note These chapters provide a logical grouping of related information and they present one. Introduction This guide provides instructions and information that will help you create components for PSoC Creator. This guide is intended for advanced users to create sophisticated components that other users employ to interact with PSoC Creator. there are some basic principles in this guide that will also benefit novice users who may wish to create their own components.

3 References This guide is one of a set of documents pertaining to PSoC Creator. and icon names in procedures: Click the Debugger icon.Introduction 1. Document # 001-42697 Rev. Displays cautions or functionality unique to PSoC Creator or the PSoC device.2 Conventions The following table lists the conventions used throughout this guide: Convention Courier New Italics [bracketed. and then click Next. bold] File > New Project Bold Text in gray boxes Usage Displays file locations and source code: C:\ …cd\icc\. 1. *G . Refer to the following documents as needed:       PSoC Creator Online Help PSoC Creator Customization API Reference Guide PSoC Creator Tuner API Reference Guide PSoC Creator System Reference Guide PSoC 3/5 Technical Reference Manual (TRM) Warp™ Verilog Reference Guide 10 PSoC Creator Component Author Guide.hex Displays keyboard commands in procedures: [Enter] or [Ctrl] [C] Represents menu paths: File > New Project > Clone Displays commands. user entered text Displays file names and reference documentation: sourcefile. menu paths and selections.

Added Bootloader chapter. Updated the customization section with current APIs. *C 5/27/09 Updates to all sections to remove TBDs and TODOs. Added UDB Clock primitive. Updated Datapath Configuration Tool. *F 09/12/10 Updated Versioning section. Added section for creating debug XML files.Introduction 1. Updates to all sections. PSoC Creator Component Author Guide. *D *E 12/1/09 4/28/10 Added section for adding Schematic Macros. *G 11/1/10 Updated Verilog section in the Implementation chapter. Product name change to PSoC Creator. Updated versioning section. Added Best Practices chapter.4 Revision History Document Title: PSoC Creator Component Author Guide Document Number: Document # 001-42697 Revision ** *A *B Date 12/4/07 1/30/08 9/23/08 Description of Change New document. Added Tuning chapter. Changed copyright year to 2010. Added section for adding/creating compatibility file. *G 11 . moved to Appendix B. Document # 001-42697 Rev. Added section for precompiled customizers. Updates to all sections. Document name change to Component Author Guide.

Introduction 12 PSoC Creator Component Author Guide. Document # 001-42697 Rev. *G .

symbol creation. customizer source files and API source files. its name will be the same name used for all elements of that component. A PSoC Creator installation includes all the versions of components. however. Make sure that the component version is added to the component name. it is important to choose the name appropriately. *G 13 . documentation authoring. therefore.1 File Names Component file names (including any version number) must be compatible with C. A user may change the case of the givenName of a component. PSoC Creator will use the givenName in the GUI. The datasheet must contain a “Change” section for each new version of the component. map the givenName to the storageName for lookup. except schematic macros.3 File Name Length Limitations Component names should be no longer than 40 characters. you may need to use additional tools.2 Name Considerations When creating a component. Add this to the component as a separate component item just like the datasheet. All code and schematic editing.  All components produced by Cypress must have a change log. PSoC Creator Component Author Guide.   2. Creating Projects and Components This chapter covers the basic steps to create a library project and add symbols using PSoC Creator. the storageName is the lowercase version of the givenName. and use the storageName to store the files on disk.1 Cypress Component Requirements All component development should occur from inside PSoC Creator itself. 2. interface definition. 2. and Verilog. PSoC Creator will keep the "givenName" and the "storageName" for each component. Longer file names create problems with the length of path names when the component is expanded in end-user designs. and resource file names should be no longer than 20 characters. do not include the version information in the display name (catalog placement). make sure that all the versions of a given component are provided for inclusion in PSoC Creator. Therefore. 2. which are all are case sensitive. Also. such as the Datapath Configuration Tool on page 127. The givenName can be mixed case. should occur within a given component. Document # 001-42697 Rev. etc.1. as the tool will add this for you.2. UNIX.1..1. This log file should be a simple text file.

CyCounter8_v1_20 is version 1." For example. when the user installs an updated component. Note that it is under the control of the component author to name the major and minor versions. A version of the component (major and minor) is fully self-contained.g. Note that since patches are an aspect of the component. The following are recommendations for external customers developing their own components. API changes.  Major version: major changes (e. bug fixes to the existing functionality of the component that do not break the compatibility. Patching may be used rarely and only when it does not change any actual content (perhaps just a document change).4 Component Versioning Cypress follows the following component version policy. PSoC Creator supports component versioning and patching. Bug fixes.) that may break the compatibility Minor version: No API changes. Incorporating the version number as part of the component name will protect existing designs when there is a major change in the component. For example. component symbol interface changes. *G .1. which is documented more fully by an internal specification. The patch level will be an aspect of the component (carried on the symbol) and hence is not reflected in the component name. Document # 001-42697 Rev. where <major_num> and <minor_num> are integers that specify the major and minor versions respectively. Major and minor numbers are each integers on their own and do not make up a "real number.   The version number will be carried as part of the component name by appending "_v<major_num>_<minor_num>" to the component name.20 of the CyCounter8 component. Documentation. additional features that do not break the compatibility Patch: No API changes. they automatically get these changes.Creating Projects and Components 2. v1_1 is not the same as v1_10 and v1_2 comes before v1_10. 14 PSoC Creator Component Author Guide. functionality changes etc.

2. there will only be one PSoC Creator library project containing components. As more components are developed over time. and select the PSoC Library project template. *G 15 . PSoC Creator Component Author Guide. 4. if desired.Creating Projects and Components 2. click the ellipsis (. The project displays in the Workspace Explorer under the Source tab. Component authors will create components separately in that project. Click OK. Cick the Other tab. Enter a Name for the project and. Document # 001-42697 Rev. Click File > New > Project to open the New Project dialog. To create a library project: 1. it may be necessary to create separate library projects for different kinds of components.) button to specify the Location to store the project...2 Create a Library Project Initially. 3.

) 1. however. Refer instead to the PSoC Creator Help for instructions. or Verilog file. Document # 001-42697 Rev. open the appropriate PSoC Creator Library project.1 Create an Empty Symbol This section describes the process to create an empty symbol and add shapes and terminals. This section will focus on creating a symbol as the first component item. When you add a new component item. The process used to add any of these component items is the same. 16 PSoC Creator Component Author Guide. Click on the Components tab of the Workspace Explorer. As needed. schematic.Creating Projects and Components 2. but this section will not cover that process. 2. *G . 2. (See Create a Symbol using the Wizard on page 19 for an alternate method of creating a symbol.3. you also create a component indirectly.3 Add a New Component Item (Symbol) The first step in the process of creating a component is to add one of several types of new component items to your project including a symbol. There are two methods to create a symbol: an empty symbol and the symbol wizard. Note You may also auto-generate a symbol from a schematic. each of the component items requires a different set of steps to complete.

including version information. the Target options are disabled. Enter the Component name. and API source files will inherit this component name. and that symbol is always generic... *G 17 . Note The symbol and all component elements except schematic macros.Creating Projects and Components 3. The Add Component Item dialog displays. customizer source files. See Name Considerations on page 13 and Component Versioning on page 14. Also. 4. Thus. Right-click on the project and select Add Component Item. Select the Empty Symbol icon. PSoC Creator Component Author Guide. Document # 001-42697 Rev. 5. there can be only one symbol file in the component.

Creating Projects and Components 6. Document # 001-42697 Rev.cysym) listed as the only node.cysym file. 8. The Symbol Editor also opens the . Click File > Save All to save changes to your project and symbol file. *G . Click Create New to allow PSoC Creator to create a new symbol file. The symbol displays in the Workspace Explorer tree. Note You can also select Add Existing from the pull-down menu to select an existing symbol file to add to the component. Note The plus sign (or crosshairs) in the middle of the Symbol Editor canvas depicts the origin of your symbol drawing. and you can draw or import a picture that represents the component. Refer to the PSoC Creator Help for more information. 7. 18 PSoC Creator Component Author Guide. Draw basic shapes and terminals to define the symbol using the Symbol Editor. with a symbol file (.

1. enter the Name. *G 19 .Creating Projects and Components 2. Under Add New Terminals. 2. Type.3. the Symbol Creation Wizard displays. PSoC Creator Component Author Guide.2 Create a Symbol using the Wizard The Add Component Item dialog contains a Symbol Wizard icon in addition to the Empty Symbol icon. Instead of choosing the Empty Symbol icon in Step 4. choose the Symbol Wizard icon. After clicking OK on the Add Component Item dialog. Follow the instructions for creating a component as described in Create an Empty Symbol on page 16. 3. Document # 001-42697 Rev. The benefit of using this wizard template is that PSoC Creator will create the basic symbol drawing and terminals for you. and Direction for the terminals you wish to place on the symbol.

*G . as needed. However. and it will be centered on the crosshairs. 4. Click File > Save All to save changes to your project and symbol file. Document # 001-42697 Rev. the new component displays in the Workspace Explorer tree. 20 PSoC Creator Component Author Guide.cysym) listed as the only node.Creating Projects and Components The Symbol Preview section will show a preview of how your symbol will appear on the Symbol Editor canvas. As with creating an empty symbol. 5. 6. Click OK to close the Symbol Creation Wizard. with a symbol file (. your Symbol Editor will display the symbol created by the wizard. Make changes to your symbol drawing.

 The name can be almost whatever you want. refer to Data Types on page 121. A parameter consists of a Name. The various properties for each parameter control how the parameter displays and behaves.    PSoC Creator Component Author Guide. See Define Symbol Parameters on page 24 for more information about these properties. For a description of the data types. and properties. validators. *G 21 .1 Parameter Overview Parameters in PSoC Creator are a set of one or more named expressions that define the behavior of a component. New parameter names cannot start with the string "CY_" or any case variation. and an associated list of properties. Type. Value. Defining Symbol Information This chapter covers the process to define various symbol information. the prefix "CY_" is reserved for built-in parameters. Document # 001-42697 Rev. The value is the default value for the instantiated component. 3. The type is a pull-down menu listing all the data types available. such as parameters. You define parameters for a symbol using the Parameters Definition dialog.3. however.

 22 PSoC Creator Component Author Guide. Users can change the values of the formal parameters to expressions. switch to an alternate implementation or version of a component. Orphan parameters will become active if the associated symbol is refreshed and now has formal parameters of those names. In a symbol. but the symbol changed. Local parameters exist for the convenience of the component author.Defining Symbol Information 3. The formals are the primary interface for the symbol. The elaborated schematic parameters are just a direct copy of the instance parameters from the parent instance. An in-memory instance has both an active parameter set and an orphan parameter. It isn't editable. and those parameters are no longer valid parameters. 3. Instance parameters match-by-name with symbol parameters. Orphan parameters are transient. but may not refer to any parameters from the schematic on which it was dropped. Formal parameters on an instance may refer to any parameters that exist on the schematic on which it was dropped. CY_INSTANCE_SHORT_NAME – If for some reason a component author needs the short form of the instance name even in the elaborated design. An instance of a component holds formal parameters from the component’s symbol. Before elaboration this parameter contains the value "__UNELABORATED__".1 Formal versus Local Parameters Symbols have two kinds of parameter definitions: formals and locals. then it does not have a parameter set. Endusers should NEVER see this.1. The instance creates a copy of its formal symbol parameters when it is dropped in a schematic. Currently. this allows end users to change their library search path. the parameter set is an evaluation context (for the local parameters). it can be accessed via this parameter. The active set are those parameters contained in the symbol's parameter set. *G . The names and the types of built-ins cannot not be changed. When open in the editor. PSoC Creator includes the following built-in parameters:  CY_COMPONENT_NAME – This parameter contains the file system path to the component's base directory (the directory where the symbol exists).2 Built-In Parameters Built-In parameters are defined for each symbol by default.1. In effect. That means they can refer to any other parameter on the instance. These parameters are not directly visible in PSoC Creator. Formal parameters are the means by which the user’s configuration values get propagated through the design hierarchy by component developers. and switch back to their original search path without losing any data. For example. Its value is automatically updated whenever the user modifies the INSTANCE_NAME parameter. End users cannot change the values of the local parameters. It is only valid after elaboration. type does not matter. Built-in parameter definitions cannot be removed from the parameter definition editor. The orphan set are those parameters that had been created for the instance. The instance local parameters are evaluated in the context of the instance. Document # 001-42697 Rev. The identifiers in the local parameter expressions come from the combined set of formal and local parameters. except by editing the schematic’s symbol. end users never see or edit them. If a schematic does not have a symbol. end users of a component are only allowed to view and configure formal parameters. Formal parameters on an instance may not refer to any of its other parameters. Schematic documents have a parameter set. See the Expression Evaluator appendix on page 121 for more information on evaluation contexts and their use. formal parameters have constant default values and local parameters may have expressions with identifiers that refer to other parameters. the schematic has a parameter set that is a direct copy of its symbol parameter set. This copy is made at run time and is guaranteed to always stay in sync with the symbol.

In the elaborated design. It works in conjunction with the live mux to allow component authors to dynamically switch between two different implementations of a component in a single schematic. *G 23 .Defining Symbol Information  CY_MAJOR_VERSION – This parameter contains the major version number for the attached instance. Document # 001-42697 Rev. otherwise it returns false. string GetShortIntsanceName() – Returns the short form of the instance name. The full hierarchical instance name is not available in the schematic editor. CY_MINOR_VERSION – This parameter contains the minor version number for the attached instance. bool IsValidCCppIdentifierName(string) – Returns true if the given string is a legal C and C++ identifier name. bool or error IsValidCCppIdentifierNameWithError(string) – Returns boolean true if the given string is a legal C and C++ identifier name. In the editor. CY_SUPPRESS_API_GEN – This parameter can be used to indicate that a particular instance should not have an API generated for it (even though the component has an API). it returns the path name of the instance. int GetMajorVersion() – Returns the major version number of the component. The default value is false. and it will have an appropriate value. In other words. string GetHierInstanceName() – Returns the hierarchical instance name.1. This is typically used to validate user input when renaming a component instance. If you want to set a parameter value to the result of one of these functions then just set the value to the function. INSTANCE_NAME – This is a special parameter.           You can make an expression that contains a function call.     3. return true. Note The INSTANCE_NAME parameter returns a different value when used in the expression evaluator versus API and HDL generation. Similarly. string GetMarketingNameWithVersion() – Returns the full marketing name and version of the current running version of PSoC Creator. it will return the same value as GetShortInstanceName(). This is the design-wide unique name given to an instance. these functions can be used in a validator expression. it returns the leaf name of the instance. this name is nearly always the one component authors should refer to. int GetMinorVersion() – Returns the minor version of the component. Returns a value of the error type with appropriate message if the identifier is not a legal C or C++ identifier. when used for API and HDL generation. use the format `=IsError()` for example. string GetComponentName() – Returns the name of the component. string GetErrorText(error) – Returns the error message stored in a value of the error type. For the expression evaluator.  bool IsAssignableName(string) – Returns true if the given instance name may be legally applied to the component instance. This is the name that should be used (via `$INSTANCE_NAME`) in API files to ensure that there aren't any collisions). bool IsError(anyType) – If the type of the argument is the error type. This is what the user edits when they want to rename an instance. it provides access to the "full" or "hierarchical" instance name. Otherwise return false.3 Expression Functions Anyone can access the following functions by using them in an expression. This is the name as entered by the user in the schematic. In this case. keep the instance around). it has the short name for the instance. See also Add Parameter Validators on page 26. CY_REMOVE – This parameter is a flag to the elaborator which tells it to remove the instance from the netlist. The default value is false (that is. In order to use one of the functions in a text label. PSoC Creator Component Author Guide.

Type.1.Defining Symbol Information 3. See Formal versus Local Parameters on page 22 for more information. If the default value for the component is subsequently changed. to open the Parameters Definition dialog. This symbol is placed in a top-level schematic with another symbol for the fixed function block. User-defined types can be "inherited. 3. Click the Formals tab or the Locals tab to define parameters as formals or locals. Right-click and select Symbol Parameters. *G . you can create any number of parameters. This is a way to group parameters together. 2. 4. You could re-define all of the enumerated types and open up error possibilities or the top-level component can use (inherit) the enumerated types from the lower level component. 3. you can create a UDB implementation of the counter that is the Verilog implementation and a symbol." For example.. that value does not get propagated down to any previously instantiated component.. and Value of a parameter in the parameter table on the left side of the dialog. Note The default parameter value only defines the value used when a component is first instantiated. 24 PSoC Creator Component Author Guide.4 User-Defined Types User-defined types (or enumeration types) are used to define parameters for symbols whose value comes from the enumeration. The value is a snap shot at that time.2 Define Symbol Parameters To define parameters for a symbol: 1. 5. For each symbol. See Define Symbol Parameters on page 24 and Add User-Defined Types on page 27. Begin by defining the Name. Document # 001-42697 Rev. define the following properties on the right side of the dialog:  Category – The category name under which this symbol displays in the Parameter Editor dialog. respectively. For each parameter. Make the symbol file active by clicking the Symbol Editor canvas or the symbol file tab.

Document # 001-42697 Rev. click OK to close the dialog. DisplayOnHover – Specifies if the parameter value displays while hovering the mouse over the instance in the Schematic Editor. x . PSoC Creator generates an expression evaluation error. x . When you are finished adding parameters. 127 0 . 32767 0 ... Hardware – Specifies if the parameter will be included in the generated Verilog netlist. Paste them by right-clicking and selecting Paste Parameter Defintions (Ctrl + V). *G 25 . See Add Parameter Validators on page 26 for how to use this field.. If out of range. Note You can copy one or more parameter definitions by right clicking and selecting Copy Parameter Defintions (Ctrl + C). Read Only – Specifies whether or not the parameter can be changed by the end user. Visible – Specifies if the parameter value is shown in the Parameter Editor dialog..Defining Symbol Information  Check Range – When true.. x . Valid ranges are as follows: Type Enumerated Type Signed 16-bit Integer Type Unsigned 16-bit Integer Type Signed 8-bit Integer Type Unsigned 8-bit Integer Type Boolean Type All Other Types Valid Range Any of the integer values that the enumerated type defines -32768 .. PSoC Creator Component Author Guide. see Appendix A for more information about CyExpressions. x . Tab – The tab name under which this symbol displays in the Parameter Editor in the Schematic Editor. 255 true and false All values are valid  Description – The description that displays to the end-user for this parameter in the Parameter Editor dialog.. Validators – One or more validation expressions for the parameter..       6. this will check that the parameter’s value after each evaluation is in the range for the associated type. 65535 -128 .

click OK. You can reference parameter names using the $ symbol. 26 PSoC Creator Component Author Guide. For example: $param1 > 1 && $param < 16 ($param1 == 8) || ($param1 == 16) || ($param1 == 24) See Appendix A for more information about the expression evaluator.3 Add Parameter Validators Parameter validation expressions are evaluated in the context of the instance. click in the Expression field for an empty row marked with >*. and press the [Delete] key. The validation expressions can refer to both formal and local parameters.Defining Symbol Information 3. 4. click in the Validators field and then click the ellipsis button. On the Parameters Definition dialog. type in the validation check expression. In the Error Message field. and type in the fields as appropriate. click the > symbol in the the first column of the row to delete. To add another validator. *G . 5. 6. To delete an expression. 3. In the Expression field. The Parameter Validators dialog displays. 2. To close the dialog. Document # 001-42697 Rev. type in the message to display if the validation check is not met. To add a parameter validator: 1.

Enter as many enum sets as needed and click OK to close the Enumeration Types dialog. Note Be careful to not use punctuation that might be interpreted as an expression. click Add to create a new enumerated type. 3. 2. enter a string in Display Name that will display in the Value pull down menu in the Parameters Definition dialog. For example use "Clock with UpCnt & DwnCnt" instead of “Clock + UpCnt & DwnCnt. type a value under Value or accept the default. button on the Parameters Definition dialog to open the Enumeration Types dialog.. Document # 001-42697 Rev." 6. PSoC Creator Component Author Guide. 5. Replace “EnumType_1” with the name you wish to use and press [Enter]. Click the Types. click in the first row under Name and type a name for the 1st name/value pair of the enumerated type. Under Type Names. *G 27 .4 Add User-Defined Types To create a user-defined type: 1..Defining Symbol Information 3. Optionally. 4. Under Enum Sets.

the generated file would be Counter_1_Counter. For example.    28 PSoC Creator Component Author Guide.5 Specify Document Properties Every symbol contains a set of properties that define different aspects of that symbol.CatalogPlacement – Defines how the component will display in the Component Catalog.DefaultInstanceName – Defines the default instance name for components.  Doc. the generated header file for a component with instance name “Counter_1” will be Counter_1.Defining Symbol Information 3. the instance name defaults to the component name. Note The APIPrefix is only applied to API files that are part of a project on disk. It is not applied to API files generated by the API customizer.SymbolSummary – Used to enter a brief description that displays in the Component Catalog. See Define Catalog Placement on page 29. if you enter “Counter” as shown above for a counter component. Document # 001-42697 Rev.h. If you enter nothing in this property. You can specify the following document properties for each component:  Doc. Doc. Doc.SymbolVisibleInCatalog – Specifies whether the component displays in the Component Catalog: true or false.APIPrefix – Specifies a prefix that will be stripped on all API files in the component before generating the final user-visible file name during code generation. right-click on the symbol canvas and select Properties. If left blank. To open the Properties dialog. Doc.h. *G .

PSoC Creator Component Author Guide. and the display name (d) is PGA: Cypress/Analog/Amplifiers/PGA. Click OK to close the dialog. Note The default parameter value only defines the value used when a component is first instantiated. enter default parameter values for this particular catalog placement definition. d – The display name for the symbol (optional). 5. 2. On the left side of the dialog. If you do not define catalog placement information. Document # 001-42697 Rev. using the following syntax: t/x/x/x/x/d t – The tab name. add more rows in the left side table to enter more than one catalog placement definition. You must have at least one node. 1. under Default Parameter Values. as needed. *G 29 . For example. in the default Component Catalog for the component named “PGA. 4.1 Define Catalog Placement You can define how symbols will be displayed in the Component Catalog under various tabs and trees using the Catalog Placement dialog. that value does not get propagated down to any previously instantiated component. the second node (x) is Amplifiers. the symbol name will be used instead.” the tab name (t) is Cypress. On the right side of the dialog.5. Open the dialog by clicking the ellipsis button in the Doc. The tab order displayed in the Symbol Catalog is alphabetical and case insensitive.Defining Symbol Information 3. the first node (x) is Analog. enter placement definition in the first row of the table.CatalogPlacement field in the Properties dialog. however. If the default value for the component is subsequently changed. 3. If desired. The value is a snap shot at that time. If you do not specify the display name. you must use the syntax: t/x/. set the same or different default parameter values for each additional row. the symbol will display by default under Default > Components. x – A node in the tree.

6.2 Advanced Shape Properties For some shapes. Visibility Expression – Defines an expression to evaluate whether or not the selected shape is visible.Defining Symbol Information 3. If $FlowControl is set to true in the instance. including:  Default Expression – Defines the default value for the shape expressed as <size>’b<value>.   30 PSoC Creator Component Author Guide. and <value> = the binary value. For example in the UART component. where <size> = number of bits. such as instance terminals. color. there are some advanced properties. Shape Tags – Defines one or more tags to be associated with one or more shapes for use with the shape customization code. *G . For example. select one or more shapes and click the Format Shape button..6 Define Format Shape Properties The Format Shape dialog is used to define properties for shapes. size. see Customizing Components on page 63. To open this dialog. you select a value from a pull-down menu. The types of properties available will vary depending on the selected shape(s). if false. pen type. etc. end cap. and they are similar to the shape formatting you will see in other word-processing or drawing programs.1 Common Shape Properties Most of the common shape properties in this dialog are self-explanatory. this property is defined with the variable $FlowControl for the rts_n and cts_n terminals. then these terminals display in the schematic. 3. etc. while a line offers width. For most of these properties. text offers font. 3. Document # 001-42697 Rev.6. they are hidden.

Select the Schematic icon. 4. There are several methods to implement the component: schematic. Document # 001-42697 Rev.1 Implement with a Schematic The schematic is a graphical diagram that represents the internal connectivity of the component. The Add Component Item dialog displays. When you finish creating the component. Note The schematic will inherit the component name. the necessary files are generated to provide information for use with Warp and the fitter. and software.4. instantiate it in a design. etc. Right-click on the component and select Add Component Item. You must have at least one implementation in your component. 2.1 Add a Schematic To add a schematic file to your component: 1. This chapter covers each of these methods. Adding an Implementation The implementation of your component specifies the device and how the component is implemented in that family or device. and build it (see Finishing the Component on page 81). 4.1. Verilog. *G 31 . PSoC Creator Component Author Guide.

the system will fall back on using the hierarchical instance name. or it can apply to any device. 32 PSoC Creator Component Author Guide. interrupts. and you can draw a diagram that represents the component connectivity at this time. *G . such as existing components. A component can have multiple macros. depending on the device option specified.1 Design-Wide Resources (DWR) Settings DWR settings are bound to DWR component instances (clocks. Typical use cases of the components in schematics will be prepared and made available as macros.   They are associated with an auto generated internal ID. Macros can have instances (including the component for which the macro is being defined). the . The new component displays in the Workspace Explorer tree.cydwr file will lose any settings the end user had associated with their DWR component. and give it a different name. Schematic macros are typically created to simplify usage of the components. or select Generic Device. They are associated by hierarchical instance name.2 Complete the Schematic Refer to the PSoC Creator Help section “Using Design Entry Tools > Schematic Editor” for details about using the Schematic Editor. To add a schematic macro file to your component: 1.1. 4. 4. 4. If you create a component with a DWR. with a schematic file (. Right-click on the component and select Add Component Item. The end user will use macros instead of using bare symbols. The internal ID is used to maintain the association. If you then add a new DWR component.2 Create a Schematic Macro A schematic macro is a mini-schematic that allows you to implement a component with multiple elements. pins.cysch) listed in the appropriate directory. The Schematic Editor opens the . etc).Adding an Implementation 3. If you delete a DWR from your component. terminals. Click OK. Document # 001-42697 Rev. 4. clocks. DMA. you can rename it at will with no consequence.2. and wires. Under Target. the Target options are available for selection. specify the family and/or device using the drop down menus.2. Thus. etc. 4.1 Add a Schematic Macro Document Add a schematic macro to a component in the same manner as any other type of component item.cysch file.1. The schematic can be an implementation for a specific family or device.

cymacro) listed in the appropriate directory. PSoC Creator Component Author Guide. You can also use macros to predefine I/O pin configurations necessary for a communication interface or an analog component. The names of macro file names will be unique in a component. *G 33 . and override default settings of each component. etc. Select the Schematic Macro icon. specify the family and/or device using the drop down menus. 2. and you can add components. define predefined settings such as a default clock frequency. and generic levels. There can be multiple macros at the same level.cymacro file. Under Target. with a schematic macro file (. The new component displays in the Workspace Explorer tree. depending on the device option specified. Click OK. This is different from other representations (schematic. Document # 001-42697 Rev.Adding an Implementation The Add Component Item dialog displays. Verilog) in the component. family. or select Generic Device. etc. Schematic macros "belong" to a component. The Schematic Macro Editor opens the . 4. Macros can be created at device. 3.

Refer to the component data sheet for various parameters available.4 Component Update Tool The Component Update Tool is used to update instances of components on schematics. a schematic macro itself is defined as a schematic. 2.Adding an Implementation 4. 4. The macro definition schematic is visible to the Component Update Tool and all appropriate updates are available. That schematic may contain instances of other components that can be updated via the Component Update Tool. Open the Timer symbol file. you could set the parameters of this component to override the Timer’s default values. When a macro is placed on a schematic the "macroness" of the placed elements disappears.2.3 Versioning Since macros belong to a component (see above) they are implicitly versioned through the versioning of the component. Document # 001-42697 Rev.2. *G . 5. The individual parts of the macro are now independent schematic elements. Connect the clock output to the “clock” input terminal of the Timer component. Place a clock component from the library.2. The macro name will not include the version number of the macro or component. and configure as necessary. However.2 Define the Macro The following shows an example for creating the Timer macro: 1. experiment with how you can delete the logic low or change the clock or timer settings. 34 PSoC Creator Component Author Guide. etc. right click somewhere in the empty space and select Properties from the drop down. 4. Change the component catalog placement and summary to the desired settings. Place a “Logic Low” component on the schematic and connect it to the “reset” input of the Timer. 4. Right click in the schematic macro somewhere and select Properties from the drop down. the Component Update Tool has nothing to update. Since there are no "instances" of macros on a schematic. 3. In a design project you will see the following: 7. Once you place this in your design. Make the setting to Hide the component from the component catalog. If desired. Place a Timer component from the catalog. 6.

PSoC Creator must assign a non-conflicting name before adding it to the model. When selected in the Component Catalog. The catalog placement editor allows the macro to be placed at multiple places in the component catalog. At the end of post-processing. See Specify Document Properties on page 28 for more information.2. 4.2.2. the macro is displayed with an index in parenthesis to denote that there are more than one instances of the macro with the same display name.6. A summary text field will be available in the schematic macro editor and when the macro is selected in the component catalog the text will be displayed in the preview area (handled the same way that the symbol is handled). For each instance. 4. except there are no parameters associated with the placement. Each instance. *G 35 . 4. The property will be available for editing in the macro editor.2. 4.5.8 Post-Processing of the Macro When a macro is dropped on a schematic. 4.2.2. the names of instances. Schematic macros will be listed in the component catalog similar to the way symbols are displayed in the catalog. terminal.6. and wires have to be recomputed. The base names of the items will be suffixed with numbers and incremented until a unique HDL name is available. terminal.cymacro". Macros will support this same feature. Instead.Adding an Implementation 4. 4. PSoC Creator Component Author Guide. Default filenames will be <component name>_ <[0-9][0-9]>.2. and wire names should not conflict with the existing names in the schematic. and wire is added to the schematic making sure that the HDL name being used for the item is currently not used in the schematic already. and wire in the macro.6 Document Properties Schematic macros have many of the same properties as a symbol. 4. Document # 001-42697 Rev.3 Hidden Property Macros support the hidden property the same way the symbols support it.5 Macro File Naming Conventions The extension of the macro files will be ". terminal.7 Macro Datasheets Schematic macros will not have a separate datasheet.1 Component Catalog Placement The catalog placement property for the macro is similar to symbol catalog placement. terminals. the instance. the macro’s preview area will show a link to the component's datasheet. all macros defined for a given component will be documented in a separate section of that component's datasheet.2 Summary Text PSoC Creator allows symbols to have associated "summary text" that is displayed in the component preview area when the symbol is selected in the Component Catalog.2.cymacro. If a macro display name is repeated in another component.6.1 Macro and Symbol with Same Name It is not recommended that component authors create a macro with the same name and catalog placement as the symbol since this can lead to confusion for the end user.

the names would be as follows:    If the names are already used. The appropriate #define values will be created. and wires will be as follows:    Instance: i2c_master Terminals: sclk. refer to the Warp Verilog Reference Guide.3 Implement with Verilog You can describe the functionality of your component using Verilog. and clk Wires: sclk. As a designer you are required to use this same name as your module name.1 Verilog File Requirements PSoC Creator allows for only one Verilog file per component. 4. as well as write and edit the file. see Datapath Configuration Tool on page 127. 4.v file for you to develop the digital content. their effective names are sclk. be aware that there are certain requirements. and clk_1 Wires: sclk_1.Adding an Implementation 4.3. but for example a cy_psoc3_control embedded in Verilog will not cause APIs to be generated that are normally produced when a Control Register symbol is placed on a schematic. and that PSoC Creator only supports the synthesizable subset of the Verilog language. sdata_1.9 Example Assume there is a macro with one instance (named “i2c_master”). Note Any primitive embedded in Verilog will not have an API automatically generated for it.” “sdata.2. a “ModuleName” component created in PSoC Creator will generate a ModuleName.” and “clk”) and three wires (wires are not named. and clk Instance: i2c_master_1 Terminals: sclk_1. and PSoC Creator only supports a synthesizable subset of the Verilog language. sdata_1. *G . and clk_1 If the macro is dropped again. and clk. sdata. The name of the component created with a symbol in PSoC Creator must match exactly the name of the module defined in the Verilog file. Should you choose to use a Verilog implementation. PSoC Creator allows you to add a Verilog file to your component. You also may need to use the Datapath Configuration Tool to edit datapath instance configurations. PSoC Creator also creates the Verilog file with the same name as the component. The top module in that file must be a “ModuleName” (case sensitive) for it to be built correctly in PSoC Creator. sdata. Document # 001-42697 Rev. 36 PSoC Creator Component Author Guide. respectively). terminals. sdata. If the schematic is empty and a macro is dropped on the schematic. For example. three terminals (named “sclk. then the suffix is incremented until a valid name is available. the names of the instances.

which will create a basic Verilog file with the appropriate file name. The Add Component Item dialog displays.2 Existing File If you have an existing Verilog file.. If necessary.2.v”. PSoC Creator Component Author Guide.v file and therefore must have this line before the module declaration: `include “cypress..v” 4.Adding an Implementation In the following example. Right click on the component and select Add Component Item.3. you can use the Generate Verilog tool. 4. 1. 3. navigate to the location of the file. 2. All Verilog files will use the cypress.v file. ‘include “cypress. Note The Verilog file will inherit the component name. the text entered in the Component name text box (“ModuleName”) must match the module name used in the Verilog file [“module ModuleName(…. Click the Elipsis button [. 4. Select the Verilog icon. toggle the Create New button to Add Existing.2 4.2. This file is contained in the search path for all Verilog compilations in PSoC Creator. you can add it as a component item. and basic module information based on how you have defined the symbol.3.1 Add a Verilog File New File If you do not have an existing Verilog file. Document # 001-42697 Rev. Click Add Existing.3. and click Open.)”]. 5. A file has been provided by Cypress that contains all of the constants expected in a component Verilog file.]. *G 37 . The Verilog file is added to the Workspace Explorer with the appropriate file name. You must think of the naming convention you want to follow when you create the symbol to start off the process as shown in the example above. See Verilog File Requirements on page 36. These constants are available in the cypress.

the Verilog implementation allows for Verilog2005 design and will compile into the PLDs available in the architecture. 4.1 UDB Array Changes Silicon Revision Definition To support various UDB array changes and maintain compatibility with previous silicon revisions. there are several other modules available which are optimized functions to prevent usage of the precious PLD resources.3.3 Complete the Verilog file Double-click on the Verilog file to open it. “PSoC5_ES1” could be used to determine PSoC 5 or earlier silicon. However.Adding an Implementation 4. These modules and their use are listed in the next few sections.4 4.3. 38 PSoC Creator Component Author Guide. Based on these defines.v file). the following defines are generated at build time into the netlisted design (project. In the same way. Name PSoC3_ES2 PSoC5_ES1 Expression `CYDEV_CHIP_FAMILY_USED == `CYDEV_CHIP_FAMILY_PSOC3 && `CYDEV_CHIP_REVISION_USED <= `CYDEV_CHIP_REVISION_3A_ES2 `CYDEV_CHIP_FAMILY_USED == `CYDEV_CHIP_FAMILY_PSOC5 && `CYDEV_CHIP_REVISION_USED <= `CYDEV_CHIP_REVISION_5A_ES1 The following example shows how to distinguish between “PSoC3_ES2” or an earlier version and PSoC 3 later than ES2. two local parameters (see localparam Usage and Named Parameters on page 51) in a Verilog component could be used to properly maintain component configuration for different device families and silicon revisions. and may be used: `define CYDEV_CHIP_FAMILY_UNKNOWN 0 `define CYDEV_CHIP_MEMBER_UNKNOWN 0 `define CYDEV_CHIP_FAMILY_PSOC3 1 `define CYDEV_CHIP_MEMBER_3A 1 `define CYDEV_CHIP_REVISION_3A_ES1 0 `define CYDEV_CHIP_REVISION_3A_ES2 1 `define CYDEV_CHIP_REVISION_3A_ES3 3 `define CYDEV_CHIP_FAMILY_PSOC5 2 `define CYDEV_CHIP_MEMBER_5A 2 `define CYDEV_CHIP_REVISION_5A_ES0 0 `define CYDEV_CHIP_REVISION_5A_ES1 1 `define CYDEV_CHIP_FAMILY_USED 1 `define CYDEV_CHIP_MEMBER_USED 1 `define CYDEV_CHIP_REVISION_USED 1 These defines have been updated to match the C defines from the cyfitter. Document # 001-42697 Rev.3. For UDB-based PSoC devices. Note The Verilog implementation's module name must match its component name. To provide information about the device family and silicon revision for Verilog components.4. and complete the file as needed.h file. *G . it is case sensitive. it may be necessary within the component to identify the device family and silicon revisions.

cy_ctrl_mode_0(8'h7)) ControlReg ( /* input */ .3. /* Add support of sync mode for PSoC 3 ES3 Rev */ generate if(PSOC3_ES2 || PSOC5_ES1) begin: AsyncCtl cy_psoc3_control #(.control(ctrl) ).. instead of #ifdef directives in the Verilog file for registers definition.cy_force_order(1). This allows conditionally compiled generation of the register definitions and reduces the number of #ifdef within the header file. .  GetSiliconRevision() returns the silicon revision as an integer. /* PSoC 5 ES1 or earlier */ localparam PSOC5_ES1 = (`CYDEV_CHIP_FAMILY_USED == `CYDEV_CHIP_FAMILY_PSOC5 && `CYDEV_CHIP_REVISION_USED <= `CYDEV_CHIP_REVISION_5A_ES1). PSoC Creator Component Author Guide.cy_force_order(1)) ControlReg ( /* output [07:00] */ .2 Component Configuration for Different Silicon Revisions The described local parameters are used within generate blocks of a Verilog implementation. For the example above one additional parameter is required: Name Type Expression `=((GetDeviceFamily() eq "PSoC3" && GetSiliconRevision() <= 1) || (GetDeviceFamily() eq "PSoC5" && GetSiliconRevision() <= 1)) ? "AsyncCtl" : "SyncCtl"` CtlModeReplacementString String This parameter has evaluation context and is evaluated with the GetDeviceFamily() and GetSiliconRevision() functions. Direct mode for ES2 and Sync mode for ES3): /*************************************************************************** * Device Family and Silicon Revision definitions ***************************************************************************/ /* PSoC 3 ES2 or earlier */ localparam PSOC3_ES2 = (`CYDEV_CHIP_FAMILY_USED == `CYDEV_CHIP_FAMILY_PSOC3 && `CYDEV_CHIP_REVISION_USED <= `CYDEV_CHIP_REVISION_3A_ES2). end /* SyncCtl */ endgenerate Two generate blocks in the example above result in different control register definitions in cyfitter.clock(clock). end /* AsyncCtl */ else begin: SyncCtl cy_psoc3_control #(. The definitions are as follows:   ES2: $INSTANCE_NAME_AsyncCtl_ControlReg__CONTROL_REG ES3: $INSTANCE_NAME_SyncCtl_ControlReg__CONTROL_REG To take this into account in the component’s API (header file) it is recommended to use a replacement string parameter within the component symbol file.h. .Adding an Implementation 4.g.h.4. *G 39 . It illustrates the different modes of control register block instantiation (e. /* output [07:00] */ . provided for API support of silicon revisions. These functions only return valid values during elaboration. for better readability. Document # 001-42697 Rev. one for each silicon revision.control(ctrl) ). The return value matches the values created in cyfitter.cy_ctrl_mode_1(8'h0). or -1 if not available. The following example is from the I2S_v1_50 component.

enable(). The output from the element can only drive UDB elements.5 UDB Elements The PSoC Universal Digital Block (UDB) contains several individually programmable components that can be accessed via Verilog when creating your design. Note Many references in this guide and in the component names specify “psoc3. This component allows the customer to inform the fitter about the clock behavior to enforce for that component in the UDB.3. The default is synchronous. "PSoC5". enable the type requested. Any other component will result in a DRC error in the fitter.1 Clock/Enable Specification For those portions of a UDB that utilize a clock. The element has one parameter:  sync_mode : A boolean parameter that designates whether the resulting clock should be synchronous (true) or asynchronous (false). and count7 counter. /* Clock from interconnect */ .sync_mode(`TRUE)) MyCompClockSpec ( . Document # 001-42697 Rev.clock_in(). two enumerated types were created: PSoC3SiliconRev PSoC3_ES1 PSoC3_ES2 PSoC3_ES3 0 1 2 PSoC5SiliconRev PSoC5_ES1 PSoC5_ES2 1 2 Finally the control register in the component API (header) will be defined as follows: #define `$INSTANCE_NAME`_CONTROL_REG (* (reg8 *) `$INSTANCE_NAME`_`$CtlModeReplacementString`_ControlReg__CONTROL_REG) #define `$INSTANCE_NAME`_CONTROL_PTR ( (reg8 *) `$INSTANCE_NAME`_`$CtlModeReplacementString`_ControlReg__CONTROL_REG) 4. To make the expression above more readable. as well as an enable signal for the clock. or an empty string if not available. Instantiate the element as shown: cy_psoc3_udb_clock_enable_v1_0 #(. When used in a way that requires a clock. the UDB components can be driven by a special Verilog component. The fitter will use this information to inspect the clock.5. *G . cy_psoc3_udb_clock_enable_v1_0 This primitive allows for the specification of the clock characteristics for the UDB components being driven by its output. including PSoC 3 and PSoC 5. The items contained in the UDB are the datapath. it is possible to specify the type of clock required (synchronous vs asynchronous). and make any necessary changes to the routing/implementation of the clock within the UDB to ensure it meets the requested characteristics at the output clock. 40 PSoC Creator Component Author Guide.Adding an Implementation  GetDeviceFamily() returns "PSoC3". status/statusi register. 4.” These references apply to all UDB-based PSoC devices. control register.3. /* Enable from interconnect */ .clock_out() /* Clock to be used for UDB elements in this component */ ).

3. refer to the TRM. which is capable of masking off any of the 8 bits of the datapath.Adding an Implementation 4.     Pass-Through Shift Left Shift Right Nibble Swap  Mask – The output of the shift operator is passed to a mask operator. then the operations act on the full datawidth.5. When multiple datapaths are tied together to form 16. and 32 bits. Compare 0: – Compare equal (ce0) – Compare (ACC0 & Cmask0) is equal to DATA0 and output the binary true/false to the interconnect logic for use by the hardware as necessary. A UDB-based PSoC device datapath is essentially a very small 8-bit wide processor with 8 states defined in a “control store. (Cmask0 is configurable in the static configuration.” There are also five static configuration registers that help define the overall operation. *G 41 . then the operations act on the full datawidth. The datapath is broken into the following sections:  ALU – An Arithmetic Logic Unit (ALU) is capable of the following operations on 8-bit data. which is capable of the following operations. When multiple datapaths are tied together to form 16.         Pass-Through Increment (INC) Decrement (DEC) Add (ADD) Subtract (SUB) XOR AND OR  Shift – The output of the ALU is passed to the shift operator. For full details on the datapath.Compare (ACC0 & Cmask0) is less than DATA0 and output the binary true/false to the interconnect logic for use by the hardware as necessary. FF Detection: FF0 and FF1 which compare ACC0 and ACC1 to 0xFF respectively and output the binary true/false to the interconnect logic for use by the hardware as necessary.2 Datapath(s) The following description is intended to provide a high-level description of the datapath and how it is used.)  Comparison Operators    PSoC Creator Component Author Guide.) – Compare LessThan (cl0) . 24. The control store and static configuration registers within the datapath can be configured using the Datapath Configuration Tool on page 127. Consecutive datapaths can be tied together to operate on wider datawidths using one of the pre-defined modules listed below. Document # 001-42697 Rev. and 32 bits. (Cmask0 is configurable in the static configuration.     2 Accumulator Registers: ACC0 and ACC1 2 Data Registers: DATA0 and DATA1 2 4-byte deep FIFO’s: FIFO0 and FIFO1 capable of multiple modes of operation Zero Detection: Z0 and Z1 which compare ACC0 and ACC1 to zero respectively and output the binary true/false to the interconnect logic for use by the hardware as necessary. 24. Registers – The datapath has the following registers available to the hardware and to the CPU with various configuration options defined in the static configuration registers.

Adding an Implementation

Compare 1: – Compare equal (ce1) – Compare ((ACC0 or ACC1) & Cmask1) is equal to (DATA1 or ACC0) and output the binary true/false to the interconnect logic for use by the hardware as necessary. (Cmask1 is configurable in the static configuration) – Compare Less Than (cl1) - Compare (ACC0 & Cmask0) is less than DATA0 and output the binary true/false to the interconnect logic for use by the hardware as necessary. (Cmask1 is configurable in the static configuration)

Overflow Detection: Indicates the msb has overflowed by driving ov_msb output as a binary true/false to the interconnect logic for use by the hardware as necessary.

The datapath allows for many different configurations that are common in almost every component that will be designed. Many functions within a datapath that can be implemented with Verilog fit into the PLDs. However, the PLDs will be used up very quickly, whereas the datapath is a fixed block. There will always be a trade off between the number of datapaths and PLDs available. It is up to the designer to decide which of these is a more precious resource. Some functions, such as FIFOs, cannot be implemented in the PLDs. To Instantiate a datapath or multiple consecutive datapaths in your design, use one of the following module instantiations within your Verilog module.

cy_psoc3_dp
This is the base datapath element available. There are several other elements which build on this base element and they should be used before this element is chosen, because all I/Os available on this element are listed in the instantiation. However, there are several limitations because of the architecture of UDBs in UDB-based PSoC devices, such that many of these signals have a limited number of wires in your design to which they can connect. It would be wise to always use the cy_psoc3_dp8 module when a single datapath is necessary. Each datapath has several parameters that can be passed as named parameters to the module itself. The Datapath Configuration Tool should be the method used to implement the parameters in the Verilog file for all datapaths. This tool will read a Verilog file, display all of the datapaths, and save the correct information back to the Verilog file for use by the compiler (Warp). The parameters are:

cy_dpconfig: the configuration for the datapath which includes the control store and static configurations. Default value is {128’h0,32’hFF00FFFF, 48’h0} d0_init: Initialization value for DATA0 Registers. Default value is 8’b0 d1_init: Initialization value for DATA1 Registers. Default value is 8’b0 a0_init: Initialization value for ACC0 Registers. Default value is 8’b0 a1_init: Initialization value for ACC1 Registers. Default value is 8’b0

   

42

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

Adding an Implementation

Instantiate this datapath as shown in the following example:
cy_psoc3_dp DatapathName( /* input */ /* input [02:00] */ /* input */ /* input */ /* input */ /* input */ /* input */ /* input */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* input */ /* output */ /* input */ /* output */ /* input */ /* output */ /* input */ /* output */ /* input [01:00] */ /* output [01:00] */ /* input [01:00] */ /* output [01:00] */ /* input [01:00] */ /* output [01:00] */ /* input [01:00] */ /* output [01:00] */ /* input */ /* output */ /* input [07:00] */ /* output [07:00] */ );

.clk(), .cs_addr(), .route_si(), .route_ci(), .f0_load(), .f1_load(), .d0_load(), .d1_load(), .ce0(), .cl0(), .z0(), .ff0(), .ce1(), .cl1(), .z1(), .ff1(), .ov_msb(), .co_msb(), .cmsb(), .so(), .f0_bus_stat(), .f0_blk_stat(), .f1_bus_stat(), .f1_blk_stat(), .ci(), .co(), .sir(), .sor(), .sil(), .sol(), .msbi(), .msbo(), .cei(), .ceo(), .cli(), .clo(), .zi(), .zo(), .fi(), .fo(), .cfbi(), .cfbo(), .pi(), .po()

// // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // //

Clock Control Store RAM address Shift in from routing Carry in from routing Load FIFO 0 Load FIFO 1 Load Data Register 0 Load Data Register 1 Accumulator 0 = Data register 0 Accumulator 0 < Data register 0 Accumulator 0 = 0 Accumulator 0 = FF Accumulator [0|1] = Data register 1 Accumulator [0|1] < Data register 1 Accumulator 1 = 0 Accumulator 1 = FF Operation over flow Carry out Carry out Shift out FIFO 0 status to uP FIFO 0 status to DP FIFO 1 status to uP FIFO 1 status to DP Carry in from previous stage Carry out to next stage Shift in from right side Shift out to right side Shift in from left side Shift out to left side MSB chain in MSB chain out Compare equal in from prev stage Compare equal out to next stage Compare less than in from prv stage Compare less than out to next stage Zero detect in from previous stage Zero detect out to next stage 0xFF detect in from previous stage 0xFF detect out to next stage CRC Feedback in from previous stage CRC Feedback out to next stage Parallel data port Parallel data port

cy_psoc3_dp8
This is a single 8-bit wide datapath element. This element has the same parameters for each datapath as the base datapath element. All parameters are appended with “_a” to indicate the LSB datapath (X=a for LSB datapath in the list below).

cy_dpconfig_X,: the configuration for the datapath which includes the control store and static configurations. Default value is {128’h0,32’hFF00FFFF, 48’h0} d0_init_X: Initialization value for DATA0 Registers. Default value is 8’b0

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

43

Adding an Implementation

  

d1_init_X: Initialization value for DATA1 Registers. Default value is 8’b0 a0_init_X: Initialization value for ACC0 Registers. Default value is 8’b0 a1_init_X: Initialization value for ACC1 Registers. Default value is 8’b0

Instantiate this datapath as shown in the following example:
cy_psoc3_dp8 DatapathName( /* input */ /* input [02:00] */ /* input */ /* input */ /* input */ /* input */ /* input */ /* input */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ /* output */ );

.clk(), .cs_addr(), .route_si(), .route_ci(), .f0_load(), .f1_load(), .d0_load(), .d1_load(), .ce0(), .cl0(), .z0(), .ff0(), .ce1(), .cl1(), .z1(), .ff1(), .ov_msb(), .co_msb(), .cmsb(), .so(), .f0_bus_stat(), .f0_blk_stat(), .f1_bus_stat(), .f1_blk_stat()

// // // // // // // // // // // // // // // // // // // // // // // //

Clock Control Store RAM address Shift in from routing Carry in from routing Load FIFO 0 Load FIFO 1 Load Data Register 0 Load Data Register 1 Accumulator 0 = Data register 0 Accumulator 0 < Data register 0 Accumulator 0 = 0 Accumulator 0 = FF Accumulator [0|1] = Data register 1 Accumulator [0|1] < Data register 1 Accumulator 1 = 0 Accumulator 1 = FF Operation over flow Carry out Carry out Shift out FIFO 0 status to uP FIFO 0 status to DP FIFO 1 status to uP FIFO 1 status to DP

cy_psoc3_dp16
This is two 8-bit wide datapath elements set up to be two consecutive datapaths for a 16-bit wide module. ALU, Shift, and Mask operations operate on the full 16-bit width of the data by having direct connections of the carry, shift-in, shift-out, and feedback signals between the individual datapaths. This element has the same parameters for each datapath as the base datapath element. All parameters are appended with “_a” to indicate the LSB datapath and “_b” to indicate the MSB of the two datapaths (X=a for LSB datapath and X=b for MSB datapath in the list below).

cy_dpconfig_X,: the configuration for the datapath which includes the control store and static configurations. Default value is {128’h0,32’hFF00FFFF, 48’h0} d0_init_X: Initialization value for DATA0 Registers. Default value is 8’b0 d1_init_X: Initialization value for DATA1 Registers. Default value is 8’b0 a0_init_X: Initialization value for ACC0 Registers. Default value is 8’b0 a1_init_X: Initialization value for ACC1 Registers. Default value is 8’b0

   

44

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

. .ff0().cl0(). Document # 001-42697 Rev. . shift-in. X=b for the middle datapath. . “_b” to indicate the middle datapath.f1_bus_stat(). . .cmsb(). .ce0().z0().ov_msb(). . . All parameters are appended with “_a” to indicate the LSB datapath.ce1().  cy_dpconfig_X.f0_load().32’hFF00FFFF. .cl1(). 48’h0} d0_init_X: Initialization value for DATA0 Registers. and Mask operations operate on the full 24-bit width of the data by having direct connections of the carry. .cs_addr(). ALU. Default value is {128’h0.f0_blk_stat().co_msb(). . . . . and feedback signals between the individual datapaths. . Default value is 8’b0 a0_init_X: Initialization value for ACC0 Registers. and “_c” to indicate the MSB datapath of the three datapaths (X=a for LSB datapath. Default value is 8’b0     PSoC Creator Component Author Guide. *G 45 .f0_bus_stat(). . . . Default value is 8’b0 a1_init_X: Initialization value for ACC1 Registers. Shift.Adding an Implementation Instantiate this datapath as shown in the following example: cy_psoc3_dp16 DatapathName( /* input */ /* input [02:00] */ /* input */ /* input */ /* input */ /* input */ /* input */ /* input */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ /* output [01:00] */ ). . and X=c for MSB datapath in the list below). shift-out.f1_blk_stat() // // // // // // // // // // // // // // // // // // // // // // // // Clock Control Store RAM address Shift in from routing Carry in from routing Load FIFO 0 Load FIFO 1 Load Data Register 0 Load Data Register 1 Accumulator 0 = Data register 0 Accumulator 0 < Data register 0 Accumulator 0 = 0 Accumulator 0 = FF Accumulator [0|1] = Data register 1 Accumulator [0|1] < Data register 1 Accumulator 1 = 0 Accumulator 1 = FF Operation over flow Carry out Carry out Shift out FIFO 0 status to uP FIFO 0 status to DP FIFO 1 status to uP FIFO 1 status to DP cy_psoc3_dp24 This is three 8-bit wide datapath elements set up to be three consecutive datapaths for a 24-bit wide module.route_ci().route_si(). . This element has the same parameters for each datapath as the base datapath element. .z1(). .clk().so().ff1().: the configuration for the datapath which includes the control store and static configurations. Default value is 8’b0 d1_init_X: Initialization value for DATA1 Registers.d1_load().f1_load().d0_load(). .

ff1(). shift-out. . .cl1(). “_b” to indicate the lower middle datapath. shift-in.f0_blk_stat().Adding an Implementation Instantiate this datapath as shown in the following example: cy_psoc3_dp24 DatapathName( /* input */ /* input [02:00] */ /* input */ /* input */ /* input */ /* input */ /* input */ /* input */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ /* output [02:00] */ ).clk(). .  cy_dpconfig_X. . ALU.route_ci(). . .f1_bus_stat().ce0(). .so().f0_bus_stat(). . and Mask operations operate on the full 32-bit width of the data by having direct connections of the carry. Default value is 8’b0 a1_init_X: Initialization value for ACC1 Registers. Default value is {128’h0.f1_blk_stat() // // // // // // // // // // // // // // // // // // // // // // // // Clock Control Store RAM address Shift in from routing Carry in from routing Load FIFO 0 Load FIFO 1 Load Data Register 0 Load Data Register 1 Accumulator 0 = Data register 0 Accumulator 0 < Data register 0 Accumulator 0 = 0 Accumulator 0 = FF Accumulator [0|1] = Data register 1 Accumulator [0|1] < Data register 1 Accumulator 1 = 0 Accumulator 1 = FF Operation over flow Carry out Carry out Shift out FIFO 0 status to uP FIFO 0 status to DP FIFO 1 status to uP FIFO 1 status to DP cy_psoc3_dp32 This element is four 8-bit wide datapath elements set up to be four consecutive datapaths for a 32-bit wide module.cmsb(). This element has the same parameters for each datapath as the base datapath element.: the configuration for the datapath which includes the control store and static configurations. . . X=b for the lower middle datapath.ov_msb().z1(). *G . Document # 001-42697 Rev.32’hFF00FFFF.ce1().cl0().f1_load(). . Shift. Default value is 8’b0     46 PSoC Creator Component Author Guide. .d0_load(). . . . . .f0_load(). and X=d for MSB datapath in the list below). . . .route_si(). Default value is 8’b0 d1_init_X: Initialization value for DATA1 Registers. All parameters are appended with “_a” to indicate the LSB datapath. X=c for the upper middle datapath. Default value is 8’b0 a0_init_X: Initialization value for ACC0 Registers. .z0(). “_c” to indicate the upper middle datapath. . . and feedback signals between the individual datapaths.cs_addr().ff0(). 48’h0} d0_init_X: Initialization value for DATA0 Registers.d1_load(). .co_msb(). and “_d” to indicate the MSB datapath of the four datapaths (X=a for LSB datapath.

z1().cy_force_order(`TRUE)) ControlRegName( /* output [07:00] */ .cmsb(). .f0_bus_stat(). Multiple control registers may be defined within a design but they will act independently. .f1_bus_stat(). . . .co_msb().cy_init_value (8'b00000000). .cl0(). .ce0().f0_blk_stat(). . Document # 001-42697 Rev. .cl1(). To instantiate a control register in your design.ff1(). . . .so(). . PSoC Creator Component Author Guide. . .f1_blk_stat() // // // // // // // // // // // // // // // // // // // // // // // // Clock Control Store RAM address Shift in from routing Carry in from routing Load FIFO 0 Load FIFO 1 Load Data Register 0 Load Data Register 1 Accumulator 0 = Data register 0 Accumulator 0 < Data register 0 Accumulator 0 = 0 Accumulator 0 = FF Accumulator [0|1] = Data register 1 Accumulator [0|1] < Data register 1 Accumulator 1 = 0 Accumulator 1 = FF Operation over flow Carry out Carry out Shift out FIFO 0 status to uP FIFO 0 status to DP FIFO 1 status to uP FIFO 1 status to DP 4. .f1_load().cs_addr().ov_msb(). . cy_psoc3_control This 8-bit control register has the following available parameters. The default value is False.ff0(). .3.d1_load(). . use the following element instantiation within your Verilog code.5.  Instantiate this control register as shown in the following example: cy_psoc3_control #(. . Typically the order is important and this should be set to TRUE. . . .Adding an Implementation Instantiate this datapath as shown in the following example: cy_psoc3_dp32 DatapathName( /* input */ /* input [02:00] */ /* input */ /* input */ /* input */ /* input */ /* input */ /* input */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ /* output [03:00] */ ).clk().d0_load().z0().3 Control Register A control register is writeable by the CPU. as follows:  cy_force_order: A Boolean used by the compiler to improve ability of the router if order of the bits within the register is not required. Each of its 8 bits are available in the interconnect routing to control PLD operations or datapath functionality.f0_load().ce1(). *G 47 . .route_si().route_ci(). cy_init_value: The initial value for the register to be loaded during chip configuration. .control() ).

3.cy_md_select(8'b00000000)) StatusRegName ( /* input [07:00] */ .   48 PSoC Creator Component Author Guide. cy_md_select: A mode definition for each of the bits in the register. The software enable is in the Aux Control register. // Status Bits /* input */ . The default value is False.  Instantiate this status register as shown in the following example: cy_psoc3_status #(.5.4 Status Register A status register is readable by the CPU. cy_psoc3_status This is an 8-bit status register. Note that multiple bits in the Aux Control register can be for different components. This is shown below in the cy_psoc3_statusi module. The bits represent transparent or sticky. cy_psoc3_statusi This module is a 7-bit status register with an interrupt output based on those 7 status bits.Adding an Implementation 4. Typically the order is important and this should be set to TRUE. The default value is False. The bits represent transparent or sticky. The default value is 0. which allows for 7 bits of status and the 8th bit is used as an interrupt source by OR’ing together the masked output of the other 7 bits. Typically the order is important and this should be set to TRUE. See the following for an example /* example code */ The module has the following parameters which should be passed as named parameters as shown in the example instantiation below:  cy_force_order: A Boolean used by the compiler to improve ability of the router if order of the bits within the register is not required. which disables all 7 bits as interrupt generators. Both enables must be enabled to generate an interrupt. The default value is transparent for each bit. . use one of the following module instantiations within your Verilog code. Each of its 8 bits are available in the interconnect routing to provide status from the PLDs or datapaths. // Reset from interconnect /* input */ . For the statusi register. The element has the following available parameters.clock() // Clock used for registering data ). there is a hardware enable and a software enable. so an interrupt safe implementation should be done using Critical Region APIs. The default value is transparent for each bit. Multiple status registers may be defined within a design but they will act independently. These should be passed as named parameters as shown in the example instantiation below:  cy_force_order: A Boolean used by the compiler to improve ability of the router if order of the bits within the register is not required. cy_int_mask: A mask register to select which bits are included in the generation of any of the 7 bits of the register. To instantiate a status register in your design.status().cy_force_order(`TRUE). *G . Document # 001-42697 Rev. An adaptation of the 8-bit status register is also implemented.reset(). cy_md_select: A mode definition for each of the bits in the register.

// Enable signal used if cy_route_en = TRUE /* output [6:0] */ .5 Count7 A simple 7-bit counter is available to avoid using up a whole 8-bit datapath or multiple PLDs to implement the same. Default is `FALSE. cy_route_en: A Boolean to enable a routed signal as an enable to the counter. // Status Bits /* input */ . if true then the counter is only enabled while the enable input is high.reset().cy_route_en(`FALSE)) Counter7Name ( /* input */ . // Reset from interconnect /* input */ . cy_route_ld: A Boolean to enable a routed signal as a load signal to the counter. // Clock used for registering data /* output */ . If your counter is between 3 and 7 bits then this module will save PLD or datapath resources.status().clock(). 4. . .load().cy_force_order(`TRUE). *G 49 .reset(). there is a hardware enable and a software enable.3.cy_period(7'b1111111). // Load signal used if cy_route_ld = TRUE /* input */ . Default value is 7’b1111111.interrupt() // Interrupt signal (route to Int Ctrl) ).  Instantiate this counter as shown in the following example: cy_psoc3_count7 #(. Both enables must be enabled to get the count7 counter to count. This element uses other resources within the architecture to avoid using up the more precious PLD and datapaths. Default is `FALSE.cy_md_select(7'b0000000). If false terminal count reloads the counter with the period value passed as a parameter.Adding an Implementation Instantiate this status register as shown in the following example: cy_psoc3_statusi #(. PSoC Creator Component Author Guide. The software enable is in the Aux Control register. // Counter value output /* output */ .5. For the count7 counter.cy_route_ld(`FALSE).cy_int_mask(7’b1111111)) StatusRegName ( /* input [06:00] */ .tc() // Terminal Count output ). . // Clock /* input */ .enable(). Note that multiple bits in the Aux Control register can be for different components. if true either terminal count or the load signal will load the counter. // Reset /* input */ . Document # 001-42697 Rev. See the following for an example /* example code */ cy_psoc3_count7 This element has the following available parameters which should be passed as named parameters as shown in the example instantiation below:   cy_period: A 7-bit period value. An example of where this counter is useful is as a bit counter for communication interfaces where you need a 4-bit counter which would tie up one whole datapath or one whole 4-macrocell PLD. If false then the counter is always enabled.count(). so an interrupt safe implementation should be done using Critical Region APIs.clock (). .

h file. the value listed in the parameter will take precedence. For example.6 Fixed Blocks For all fixed blocks.8 When to use Cypress Provided Primitives instead of Logic      Register that needs to be accessed from the CPU Most ALU operations especially if it is wider than 4 bits Shifting operations especially if it is wider than 4 bits Masking operations especially if it is wider than 4 bits Counter operations especially if it is wider than 4 bits 4. This Verilog supports the standards used in Verilog 2001. 4.cy_registers("reg_name=0x##[. but the value is always interpreted as hexadecimal). which will be established before the main() function is called. #define ‘$INSTANCE_NAME_DatapathName_u0_A0_REG 0 #define ‘$INSTANCE_NAME_DatapathName_u0_A1_REG 0 #define ‘$INSTANCE_NAME_DatapathName_u0_D0_REG 0 #define ‘$INSTANCE_NAME_DatapathName_u0_D1_REG 0 50 PSoC Creator Component Author Guide.1 Generate Statements The ability to use generate statements is key to component development in UDB-based PSoC devices because you cannot use the `ifdef statement to work with parameterized values in your Verilog file. a parameter of cy_registers is available to allow you to explicitly set the values for the given registers for the block. Document # 001-42697 Rev. The values listed will be included in the configuration bitstream generated to program the part.7 Design-Wide Resources Some components are considered part of design-wide resources and are not included in Verilog files. If you use a generate statement with a “begin : GenerateSlice” statement then the components are now pushed down one level in their naming. *G . you may want to remove a datapath if the parameter set by the user requests an 8-bit wide data bus.h file) from the datapaths and control and status registers. Note It is important to remember scope when trying to define nets inside of a generate statement. Note Generate statements add a layer to the naming convention passed to the API (in the generated cyfitter.9 Warp Features for Component Creation PSoC Creator components may use Verilog to define the digital hardware of the system. such as the CR1 register of the DSM.3.9. Where reg_name is the name of a register in the block as listed in the TRM. In the case where a register listed is one that is also configured by the fitter. The value for the parameter is a string which is expected to have a format of: .3.reg_name=0x##]"). For example a datapath named “DatapathName” that is not inside of a generate statement will have the following variables defined in the cyfitter. 4.3. Warp supports Conditional and For-loop generate statements which can surround Verilog code.Adding an Implementation 4.3.3. The value after the = is expected to be the hexadecimal value to be assigned to the register (the leading 0x is optional. such as:   Interrupt Controller DMA Request 4. This can be handled with a conditional generate statement.

These are the support of localparams and passing named parameters.Adding an Implementation But if that same datapath is inside of the “GenerateSlice” generate statement the same variables will be defined in cyfitter. A parameter called MSBVal can be defined which is assigned based on the existing parameter NumBits which defines the transfer size of the block.h as #define ‘$INSTANCE_NAME_GenerateSlice_DatapathName_u0_A0_REG 0 #define ‘$INSTANCE_NAME_GenerateSlice_DatapathName_u0_A1_REG 0 #define ‘$INSTANCE_NAME_GenerateSlice_DatapathName_u0_D0_REG 0 #define ‘$INSTANCE_NAME_GenerateSlice_DatapathName_u0_D1_REG 0 For Loop Generate Example genvar i. This is critical for component development particularly when assigning the datapath configuration information. . Any Verilog Code end endgenerate Parameter Usage Parameters are allowed in the right hand side of a parameter assignment. the SPI component requires the ability to set the number of data-bits dynamically at build time. localparam Usage and Named Parameters Parameters are widely used in components because of the configurable nature of them in PSoC Creator. *G 51 . . This is used extensively as shown in the standard modules defined in previous sections. . The MSB value bit-field of the datapath’s configuration requires a different value based on the data-width of the SPI transfer. . Defparam usage is very error prone so Warp has added the support of named parameter passing. i < 4. status register isntantiation PSoC Creator Component Author Guide. The method to do this is provided in the datapath configuration tool. For example.cy_force_order(`TRUE)) StatusReg ( . For datapath configuration you should not be hand-editing the parameters passed to a datapath. Named parameters are passed at the instance declaration time within the #(…) block as shown in the following example: cy_psoc3_status #(. But you may use this method in any other parameter definitions at your discretion. generate for (i=0. It is important to protect your parameters so they are not accidentally overwritten with unexpected values. Any Verilog Code using i end endgenerate Conditional Generate Example generate if(Condition==true) begin : GenerateSlice . . i=i+1) begin : GenerateSlice . For this to work there are two features in the PSoC Creator version of Warp. . Document # 001-42697 Rev.

localparam MSBVal = (NumBits (NumBits (NumBits (NumBits (NumBits (NumBits (NumBits (NumBits endmodule == == == == == == == == 8 || 7 || 6 || 5 || 4 || 3 || 2 || 9) ? NumBits NumBits NumBits NumBits NumBits NumBits NumBits 5'd1.) parameter NumBits = 5'd8. == == == == == == == 16) 15) 14) 13) 12) 11) 10) ? ? ? ? ? ? ? 5'd8 5'd7 5'd6 5'd5 5'd4 5'd3 5'd2 : : : : : : : 4. You would not use a schematic or Verilog. In the example above for SPI.. One example of a software only component might be an interface that links the code of several components.. The code for this example would look like the following: module SPI(. just software files. 52 PSoC Creator Component Author Guide.Adding an Implementation You can and should also protect your parameters with local parameters as much as possible. Everything else in the process would be the same as any other type of component.4 Implement with Software Implementing with software is simply omitting the references for hardware. Document # 001-42697 Rev. *G . MSBVal should be defined as a local parameter because it is set based on the parameter NumBits and is not settable by the user at a higher level.

The template file assists with submitting the correct set of Verilog files. These files are located at $CYPRESS_DIR/lib/common. Although Cypress does not at this time provide a Verilog simulator. It is not used by Warp in the synthesis process where the synthesis engine uses models already defined and implemented. the file lpmsim.. creates Cypress-specific post-synthesis primitive models. this is accomplished with the +incdir+ switch (i. The latter example is valid since the Verilog source files are also mirrored at $CYPRESS_DIR/lib/prim/presynth/vlg for convenience and compatibility with the Verilog pre-synthesis file structure.v is used to define various primitives used by the synthesis engine to map to the internal architecture of the targeted devices. +incdir+$CYPRESS_DIR/lib/common or +incdir+$CYPRESS_DIR/lib/prim/presynth/vlg). In addition to the lpm. *G 53 . Simulating the Hardware This chapter describes the tools and methods used to simulate content for UDB-based PSoC component development using ModelSim and VCS. The steps needed to simulate the design in different simulator environments are described below.1 ModelSim A tool within PSoC Creator. In this chapter. these lines must also be included.v is also used for pre-synthesis simulations. the invocation of a ModelSim/Verilog simulator that utilizes these collections of modules would be: vlog +incdir+$CYPRESS_DIR/lib/common <testbench>.v is used to define certain values for the parameters used by the LPM models in the library. Typically. it is necessary for pre-synthesis to describe the architecture of the modules. The file lpm. The first file lpm. the path to these files was specified with the -i switch on the Warp command line (i. called Warp. the following lines must be present in the user’s source design: ‘include “lpm.v for designs that are not being synthesized by Warp.. In the synthesis process.v contains an ‘include clause that causes the inclusion of the file lpmsim. in the proper order.v” The former is necessary to use the LPM modules and the latter to make use of the RTL modules for inclusion in the user’s design. The second file rtl. PSoC Creator Component Author Guide. to the target Verilog compiler. However. When using these models for synthesis.v files.v” ‘include “rtl. -i$CYPRESS_DIR/lib/common). For Verilog simulators. 5.v and rtl. $CYPRESS_DIR is $INSTALL_DIR/warp/. a post-synthesis simulation model of the design.v <testfile>. Document # 001-42697 Rev.e. Warp uses two source files to accomplish the synthesis of Verilog designs.e. and a template file in the vlg sub-directory.5. For pre-synthesis simulations. some system files necessary for third party simulators to provide pre-synthesis simulations have been made available. Synthesis of Verilog source designs has been made possible with Warp.v The appropriate ‘include clause must be present in the user’s source code to access the desired modules.

UDBs interact with the main processor via a bus interface for register reads and writes through registers within the UDB. 5.2 5. The following is a short list of the tools required for a component developer: Tool VCS SIMV DVE Warp Tool Chain (PSoC Creator) Cygwin Datapath Configuration Tool Description Compiler. always begin #‘RUN_LENGTH $finish.1 VCS Tools Digital content for UDB-based PSoC devices is defined using Verilog.um_testbench).vcd file must be specified in the project. Tool for defining Datapath component configuration information. Configuration (DAT file) is read into the simulation at compile time. The development methodology also follows standard Verilog methods with a few new ways of thinking when dealing with datapaths and the UDB models available in UDB-based PSoC devices.2. Linux emulation environment used on a PC to connect to appropriate Linux machines. end  To provide a more realistic simulation environment. The test bench file includes to the following always block to prevent this. Waveform Viewer. Compiler (place and route and various other pieces) for PSoC devices.2.Simulating the Hardware 5. Verilog files (component and test bench) are compiled along with the UDB models provided from the design team (these models are located with PSoC Creator in ‘$CYPRESS_DIR/lib/sim/presynth/vlg’). Document # 001-42697 Rev. $dumpvars(0. initial begin $dumpfile("foo.vcd file (foo. This executable must be run to provide the data file for waveform viewers. Provides the X-Windows environment needed to run VCS and Undertow.vcd"). Executable generated from VCS. Compiles all of the Verilog into a simulation file. A Verilog file is written in any text editor. These provide a more accurate representation of the UDB within the UDB-based PSoC architecture. There are also a few constructs in the UDB models which provide better functionality in simulation. end As with all test benches it is necessary to specify when the simulation will end otherwise the simulation may run forever. When using VCS you must include the following items in your test bench:  The signals viewable in the . In the UDB-based PSoC digital world.vcd). *G . and most of the tools are standard Verilog development and simulation tools. The simulation environment has provided this bus interface for simulation and three tasks have been 54 PSoC Creator Component Author Guide.2 Test Bench Definition There are items required in the test bench to use VCS and undertow for simulation. The following bit of code is included in the test bench file and designates all signals from the top level (um_testbench module) down as viewable in the . a few things should be understood about the UDB-based PSoC architecture.

1). #100 bus_write(‘TXShifter. 8’h03). 8’h08). Document # 001-42697 Rev.Simulating the Hardware provided in an example test bench which allow for register reads. bus_reset( ‘TXShifter ). //Used to count //the number of bits sent #(‘CLK1M_PERIOD*0. //Disable RX to test that feature #100 bus_write(‘TXShifter. The format used to call these tasks is shown below: bus_reset( ‘datapathName ).rx_control[0] = 1’b0. reset = 1’b0. UDB_F0_ADDR. //D0 is used as a comparator //for the bit clock generator #(‘CLK1M_PERIOD*0. clkcnt = 0. DataToSend[1]). REG_NAME. bus_reset( ‘TXBitClkGen ). #1 reset = 1’b1.1). force uart. bus_reset( ‘RXBitClkGen ). bus_write(‘RXBitCounter. #197 reset = 1’b0. writes and resets. 8’h04). bus_write(‘TXShifter. //comparator for the bit clock generator //Used as a //Set TX to Disable //Set RX to Disable //Reset everything (uses the 100MHz clock //Everything is reset so start operation #(‘CLK1M_PERIOD*0.rx_control[0] = 1’b1. This should be the first byte transmitted //This holds //Let the first byte be transmitted by waiting atleast 8 clock periods #(‘CLK1M_PERIOD*20*8). This allows the flow of the test bench to be written much like firmware would.1). DataToSend[0]). UDB_D0_ADDR. bus_reset( ‘RXShifter ).tx_control[0] = 1’b1. //F0 holds the data to be sent PSoC Creator Component Author Guide. // INITIALIZE: Initialize all of the registers for // testing this includes writing the first transmit byte to the output buffer #(‘CLK1M_PERIOD*0. #800 force uart. //Set UART TX to RUN (control register write!) force uart. bus_reset( ‘TXBitCounter ). Here is an example test bench. bus_write(‘TXBitCounter.tx_control[0] = 1’b0.rx_control[0] = 1’b0. bus_write( ‘datapathName.1). //the data to be sent. // Waiting 1/10th the clock cycle is just assuming // these registers would be written by firmware // in a sequence that takes on average 10 cycles // to complete each write force uart. UDB_F0_ADDR.1). //Set UART RX to RUN (control register write!) bus_write(‘TXBitClkGen. UDB_D0_ADDR. UDB_F0_ADDR. UDB_D0_ADDR. bus_reset( ‘RXBitCounter ). bus_write(‘RXBitClkGen. UDB_D0_ADDR. force uart. 8’hDATA ). 8’h07). //FIFO_0 holds the data to be sent //Let the byte be transmitted by waiting 20 bit-clock periods //(each bit_clock period is 1/8 the Clk1M period) #(‘CLK1M_PERIOD*20*8). *G 55 . Resets of all registers are required before reading or writing to them in simulation. based on the method used for the UART component: initial begin clk100M = 1’b0. DataToSend[2]). clkcnt = 0. which is to implement a sequential series of reads and writes. //Used to count //the number of bits sent //START_TEST1: Send several bytes out the TX to test the functionality //of individual bytes and the transfer mechanism of send when data ready #(‘CLK1M_PERIOD*0.

dpTXShifter_. and uart. DataToSend[3]). bus_write(‘TXShifter. parameter UDB_A1_ADDR = 12’h010. #(‘CLK1M_PERIOD*4*8). DataToSend[4]). //END_TEST2: UDB_F0_ADDR. force uart. #(‘CLK1M_PERIOD*4*8). parameter UDB_MK_ADDR = 12’h080. #(‘CLK1M_PERIOD*4*8). //F0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO UDB_F0_ADDR. DataToSend[8]). //FIFO_0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO The bus_reset(). #(‘CLK1M_PERIOD*4*8). bus_read() and bus_write() tasks must be modified from the examples below with hard coded names of the datapaths that are being tested. parameter UDB_ST_ADDR = 12’h060. *G .dpTXShifter with your own components name and datapath instance name replace clk100M with your simulation System Clock Name Each datapath used must have a case statement associated with it for each of the three tasks UDB Registers are defined as: //Do NOT CHANGE these parameters they define the simulation Bus interface parameter UDB_A0_ADDR = 12’h000. //F0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO UDB_F0_ADDR. parameter UDB_CT_ADDR = 12’h070. //F0 holds the data to be sent //Let the byte be transmitted by waiting at least 8 clock periods #(‘CLK1M_PERIOD*20*8). bus_write(‘TXShifter. #(‘CLK1M_PERIOD*4*8). //F0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO UDB_F0_ADDR. Document # 001-42697 Rev. DataToSend[9]). parameter UDB_AC_ADDR = 12’h090. bus_write(‘TXShifter. DataToSend[6]). //Re-enable RX to test start/stop functionality. DataToSend[5]). //F0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO UDB_F0_ADDR. parameter UDB_F1_ADDR = 12’h050. parameter UDB_F0_ADDR = 12’h040. #100 bus_write(‘TXShifter. //The following TX’s will be written to the FIFO in rapid fire //so as to test the functionality of the FIFO’s and //to verify that the logic is correct for writing //bytes continuously if data is available //START_TEST2: bus_write(‘TXShifter. DataToSend[7]). bus_write(‘TXShifter. //F0 holds the data to be sent //Delay 4 bit clocks to write new data to the FIFO UDB_F0_ADDR. parameter UDB_D0_ADDR = 12’h020.    56 PSoC Creator Component Author Guide. //END_TEST1: That ends the testing of sending individual bytes. UDB_F0_ADDR. bus_write(‘TXShifter. #(‘CLK1M_PERIOD*4*8). parameter UDB_D1_ADDR = 12’h030. The figures below show the format of each task with the following caveats:   replace UART_dpTXShifter with a constant for your own datapath replace uart.Simulating the Hardware //Let the byte be transmitted by waiting at least 8 clock periods #(‘CLK1M_PERIOD*20*8).rx_control[0] = 1’b1.

dpTXShifter. # 1. input [15:00] data. input [11:00] addr.dpTXShifter. then wait for ready. input [3:0] dpaddr.dpTXShifter.U0.bi_cntl = 8’b00000000.. // de-select @(posedge clk100M).haddr = addr.. uart. wait(uart. Document # 001-42697 Rev. // hsel_wrk_8.. no hwrite uart.dpTXShifter.Simulating the Hardware  Each datapath’s bus interface clock is driven with the bus clock using one assign statement per datapath: assign uart.U0.dpTXShifter.. uart. task bus_reset...hready == 1) uart.U0. input [3:0] dpaddr. input [11:00] addr.. // reset @(posedge clk100M) # 1. @(posedge clk100M).bi_cntl = 8’b00000000. // .bi_cntl = 8’b00000010. begin case(dpaddr) ‘UART_dpTXShifter: begin PSoC Creator Component Author Guide.U0. @(posedge clk100M). assert the strobe for a full cycle .U0.U0.dpTXShifter_f0_not_empty == 1) // . # 1. wait(uart...dpTXShifter... *G 57 .U0. end endcase end endtask task bus_write.bi_cntl = 8’b00000001. input [3:0] dpaddr..bus_clk = clk100M.dpTXShifter. begin case(dpaddr) ‘UART_dpTXShifter: begin // Wait for the FIFO to be ready to be read from . begin case(dpaddr) ‘UART_dpTXShifter: begin @(posedge clk100M) # 1. uart. // un-reset end endcase end endtask task bus_read.

.75)clk50M_en = 0. hwrite uart.U0. *G . The clock dividers in the UDB-based PSoC architecture do not provide a 50% duty cycle..U0..U0.. @(posedge clk100M).U0. They actually provide a signal that is 1 high time of the main clock every 1 divide time that is chosen. // de-select @(posedge clk100M).dpTXShifter. end endcase end endtask Another UDB-based PSoC device realistic simulation model relates to the clocks available to the UDBs.75)clk50M_en = 1.U0.dpTXShifter. #(‘GCLK0_PERIOD*0..hready == 1) uart.. 1 for 50 MHz and 3 for 25 MHz): always @(posedge clk100M) begin if(clkcnt == ‘CLK50M_COUNT) begin clkcnt = 0.. @(posedge clk100M).dpTXShifter.hwdata = data. // . wait (uart. then wait for ready.. # 1. 58 PSoC Creator Component Author Guide.. Document # 001-42697 Rev. end end assign clk50M = clk100M & clk50M_en. At this time there are several clock options available. // ..bi_cntl = 8’b00010010. uart. // hsel_wrk_8. that is...haddr = addr. #(‘GCLK0_PERIOD*0.dpTXShifter.Simulating the Hardware // Wait for the FIFO to be ready to be written to .dpTXShifter. end else begin clkcnt = clkcnt+1. but one major distinction when using the clock dividers must be considered.bi_cntl = 8’b00000000. uart. assert the strobe for a full cycle . assume a 100 MHz main oscillator and 50 MHz and 25 MHz desired clock frequencies: The following Verilog code will create the desired output frequency 50 MHz with the duty cycle seen in a UDB-based PSoC (CLK50M_COUNT = (Divider-1). # 1. For example.

2 File Naming All of the files in the API directory are templates expanded into instance_name-qualified files for compilation. ‘#DECLARE_ENUM type_name‘ ‘#DECLARE_ENUM_ALL‘ – declare the key names defined for the specified typename – declare the key names for all types used by the component Note A type_name might be defined locally (PARITY) or remotely (UART__PARITY). Adding API Files This chapter covers the process of adding application programming interface (API) files and code to a component.c.2 User-Defined Types The following constructs define the mappings for user defined types.c. and both expand to provide the specified parameter value. this code snippet would expand to: void foo_1_counter_Start(void). 6.c. The hardware addresses are a result of placement (one of the steps in the fitter.1. let the Counter API files be Counter.1 API Template Expansion Parameters When creating API template code. PSoC Creator Component Author Guide. which is part of the build process).6. then files bar_1_foo_Counter. Counter. you can use any built-in. and CounterINT.3. including the generation of symbolic constants used to define hardware addresses. *G 59 . For a Counter instance named foo_1.c are generated.1 API generation API generation is the process by which PSoC Creator creates instance-based code. 6. you create API file templates for the component that become instance-specific for an end-user. foo_Counter.h.1.h.1. formal.1 API Overview API files define the component interface. which provides the various functions and parameters for a component.c are generated. and foo_CounterINT. 6. 6.1. and local parameter (including user-defined parameters) for template expansion using either of the following syntax: ‘@<parameter>‘ ‘$<parameter>‘ Either syntax is valid. For example: void `$INSTANCE_NAME`_Start(void).1. As a component author.3 6. Document # 001-42697 Rev. If there is a top-level Counter component called foo.c. For example. bar_1_foo_Counter.3.h. If there is a lower-level Counter instance called bar_1_foo. then files foo_Counter. 6. as well as different aspects such as API generation and template expansion. and bar_1_foo_CounterINT.

COTTON=2.1. an entry of: #define `$INSTANCE_NAME`__REMOVED 1 will be generated in cyfitter. if used.h to allow the component API to be conditionally compiled into the design. In addition. To inform the API generation system that the code for the component is no longer needed. Document # 001-42697 Rev. Example Component: Type: Also Uses: Component: Type: Fox Color (RED=1.4 Conditional API Generation In the specific case of control register. In the API file for bob. if the mapping of the design to the part determines that the component is not being used (based on connectivity of the component). any code that uses the APIs of the removed component would need to be constructed to take advantage of the #define so the removed component would not be accessed. status register. *G . JACKALOPE=3. BLUE=3) Rabbit__Species Rabbit Species (JACK=1. the expanded name takes the form: <path_to_instance>_<componentname>__<keyname> Note that the instance name is followed by a single underbar (as in the rest of the API). or interrupt. statusi register. WHITE=2. the mapping process will remove the component from the mapped design. This means that locally defined key values should not conflict with register names. is followed by a DOUBLE UNDERBAR (as it is in the rest of the system). 60 PSoC Creator Component Author Guide. the following lines: ‘#declare_enum Color‘ ‘#declare_enum Rabbit_Species‘ expand to: #define #define #define #define #define #define #define path_to_bob_RED 1 path_to_bob_WHITE 2 path_to_bob_BLUE 3 path_to_bob_Rabbit__JACK 1 path_to_bob_Rabbit__COTTON 2 path_to_bob_Rabbit__JACKALOPE 3 path_to_bob_Rabbit__WHITE 4 In the API file for bob. but the component name. WHITE=4) A design contains a schematic that contains one instance of Fox named bob. the following line: ‘#declare_enum_all‘ expands to: #define #define #define #define #define #define #define path_to_bob_RED 1 path_to_bob_WHITE 2 path_to_bob_BLUE 3 path_to_bob_Rabbit__JACK 1 path_to_bob_Rabbit__COTTON 2 path_to_bob_Rabbit__JACKALOPE 3 path_to_bob_Rabbit__WHITE 4 6. the expanded name takes the form: <path_to_instance>_<keyname> For borrowed types. For types local to the instance.Adding API Files Each of those directives results in a sequence of #define statements.

This is an invalid configuration except for components of type “primitive. with identical substructure. the code generation mechanism must be aware of the hierarchy when generating the APIs.  Both a schematic and an API are provided.1.. *G 61 . Likewise. When the schematic includes other instantiated components that have their own APIs. the creator of the Count32 component would need to use u1’s API in the template code as ‘$INSTANCE_NAME``[u1]`Init().  An API exists but no schematic is provided In this case. In this case.1. or only one of them (only a component of type “primitive” may have no schematic and no API). with instance names u1 and u2 in the Count32 generic schematic. You define the region using the following syntax: /* `#START <region name>` */ /* `#END` */ Anything an end-user places in this region will be preserved in subsequent updates of the file.. consider construction of a Count32 component from two Count16 components.Adding API Files 6.  Neither a schematic nor an API is provided. Note that if the Count16 component was composed of Count8 components.7 API Cases You may specify both an API and a schematic for the component. when the user edits the design-entry document for a family. the component does not re-use existing components and presents an API for use.]‘ substitution mechanism for hierarchy path generation for you to access fitter constants. only the primitives that are applicable for that particular family are available for placement into a schematic. 6.6 Merge Region A merge region defines an area where end-users can write their own code that will be preserved during future updates of components and source code. the component is nothing but a hierarchical combination of other components that needs to be flattened when instantiated in a design. If a subsequent version of the file does not contain the same named region. For example. The following lists the possible cases of APIs that may – or may not – exist:  A schematic is provided but no API exists In this case.5 Verilog Hierarchy Subsitution If you are implementing your design using Verilog. Document # 001-42697 Rev. then their instance names during code generation are hierarchical in nature as well. For example: foo_1`[uart_x. the entire region from the previous file will be copied to the end of the file and placed in comments.1. Note that when the user edits the design-entry document for the generic portion of the component project. you may wish to access various fitter constants for control registers. When the Count32 component is instantiated in a top-level design.” PSoC Creator Component Author Guide. no family-specific primitives can be placed into the schematic.ctrl]`ADDRESS This code snippet expands to: foo_1_uart_x_ctrl_ADDRESS 6. This may occur for software-only components that do not employ other components. the code generation process for a top-level design is somewhat complicated. for example. PSoC Creator provides a ‘[. This is a typical component with an API and one or more primitives and/or other components included in the design.

2 Add API Files to a Component Use PSoC Creator to add as many API files as required for the component: 1. 4.3 Complete the . Note You can specify whether the component item is for a generic device or a specific family and/ or device. (See Finishing the Component on page 81. mask.h. *G .) the full instance name will be used (including any hierarchy) with a specified string appended (as shown in the following table): Working Register Status Status Auxiliary Control Control Control Auxiliary Control Mask Period Accumulator 0 Accumulator 1 Data 0 Data 1 FIFO 0 FIFO 1 Datapath Auxiliary Control Name (Prepend <Instance name>_<GenerateSliceName> for each) _<StatusRegComponentName>_STATUS_REG _<StatusAuxCtrlRegComponentName>_STATUS_AUX_CTRL_REG _<ControlRegComponentName>_CONTROL_REG _<ControlAuxCtrlRegComponentName>_CONTROL_AUX_CTRL_REG _<MaskRegComponentName>_MASK_REG _<PeriodRegComponentName>_PERIOD_REG _<A0RegComponentName>_A0_REG _<A1RegComponentName>_A1_REG _<D0RegComponentName>_D0_REG _<D1RegComponentName>_D1_REG _<F0RegComponentName>_F0_REG _<F1statusRegComponentName>_F1_REG _<DPAuxCtlRegComponentName>_DP_AUX_CTL_REG 62 PSoC Creator Component Author Guide. Select the icon for the component item you wish to add. Click Create New.c file to open it.h file generally contains the interfaces for the component functions and parameters. 2. It provides API definitions for the component.h file The . which is generated as part of the build. Repeat the process to add more API files.) 6. For working registers (status. 6. The component item displays in the Workspace Explorer. Right click on the component and select Add Component Item. 3. and complete the file as necessary. The Add Component Item dialog displays.c file Double-click on the . Depending on the target options you specified. Select the Target option. 5. there are a few naming conventions used. Type in the Item name.Adding API Files 6. control.4 Complete the . period. Document # 001-42697 Rev. etc. When the header is generated. This file should include the file cyfitter. 6. the component item may be located in a subdirectory.

The icyinstancecustomizer. The following sections describe different aspects of the C# source code.1. and the documentation is located in the PSoC Creator Customization API Reference Guide (customizer_api. but don't have a valid customizer DLL or the customizer DLL which was created earlier is outdated. This automatic build happens in the following cases: 1. 2. You will be able to specify whether to build the customizer DLL in "Debug" or "Release" mode. The code is sometimes referred to as “customizers. and assembly references for the given project. A project is built and it or any of its dependencies have customizer source files. The cydsextensions project contains the necessary source code for customization. A project is opened and it or any of its dependencies have customizer source files.1 Protecting Customizer Source Source code customizers can depend on external assemblies. as well as specify command line options to the compiler. resource files. The component author explicitly asks PSoC Creator to build a new customizer DLL. 3.2 Development flow You will supply the C# source files. provides instructions on customization source. located in the same directory as this Component Author Guide). 7. and just invokes methods in the external assembly. So if you want to avoid distributing your customizer as source code.7. 7. PSoC Creator will build the customization DLL out of the given code automatically at run time. PSoC Creator Component Author Guide. and it lists and describes the interfaces that can be used to customize components. but don't have a valid customizer DLL or the customizer DLL which was created earlier is outdated. counts. 7.cs C# source file provides the definitive parameters and return values for the methods provided in the customizer interfaces.1 Customizers from Source PSoC Creator accepts customizers developed in C#. Customizing Components Customizing components refers to the mechanism of allowing custom code (C#) to augment or replace the default behavior of an instantiated component within PSoC Creator.1. This project is included with PSoC Creator. *G 63 . you can have a source code stub which loads an external assembly.chm file. or configuration based on parameters generate custom Verilog code generate custom C/assembly code interact with the clocking system (for clock and PWM components) This chapter provides examples for customizing a component. Document # 001-42697 Rev.” which may:       customize the Configure dialog customize symbol shapes / display based on parameter values customize symbol terminal names.

On the New Item dialog. right-click on the "Custom" directory and select Add > New Folder.” The Text Editor opens the .” 3. select the Resx file icon. Select the C# icon under “Misc. type an appropriate name for the C# file.1. These files can be stored under the "Custom" directory or in sub-directories you created. *G . Right-click on the component and select Add Component Item. the errors/warnings are displayed in the Notice List window. Document # 001-42697 Rev. For Item Name. 7.Customizing Components If there are any errors/warnings during the above build procedure. 4. 7. The Add Component Item dialog displays. and you can edit the file at this time.1.4 Create Sub-Directories in “Custom” To add a sub-directory. Click Create New. 5.cs file. Right click on the directory and choose Add > New Item.resx) for the customizers. Since the DLL is built on the fly. 2. type a name for the file.5 Add Resource Files You can add .3 Add Source File(s) To add source files to your component: 1. The component item displays in the Workspace Explorer tree. Note Any sub-directory created will be physical. there is no need to keep any of the built customizer DLLs in source control. Multiple resource files are allowed per component. 64 PSoC Creator Component Author Guide. 2. accept Generic Device. and click OK. 7.1. To add the resource file 1. in a sub-directory named “Custom.NET resource files (. Under Target.

You can add assembly references relative to the project top level directory (.0/customizer_cache/ 7.dll" "System. This class must be named "CyCustomizer". this feature can provide a performance improvement.Company.Name. However. By design.NET\Framework\v2.Drawing.1.dll" "System.NET references you will have to browse to: %windir%\Microsoft. This will build the component customizer assembly.8 Customizer cache The customizer cache is the directory where all the compiled customizer DLLs reside. To bypass loading and inspecting those files and to define the component customizer assembly to use. Checking to see if the component customizers are up to date requires inspecting all of the constituent files. In the case of .dll" "System.2 Precompiled Component Customizers A precompiled component customizer is an advanced feature. and it can take some time to load those files from disk and inspect them.my_comp my_comp Some. in the case of very large and static libraries with many component customizers (such as libraries supplied with PSoC Creator). and associate it with the PSoC Creator Component Author Guide.50727 You can also specify relative paths in the assembly references dialog. Document # 001-42697 Rev. component customizers are rebuilt when necessary.6 Name the Class / Customizer There can only be one class which will implement the required customizer interfaces. The following assemblies are automatically included:      "System.0/customizer_cache/ Similarly if the DLL is compiled during a build (within cydsfit). the directory will be located at: Documents and Settings/user_name/Local Settings/Application Data/ Cypress Semiconductor/PSoC Creator/1. browse to the directory where the assembly resides and select it. if the customizer DLL is compiled from within PSoC Creator. The location of this directory depends on the executable which is compiling the DLLs.Customizing Components 7. from within PSoC Creator itself.NET references and other user references.dll" "cydsextensions. for a component named "my_comp".my_comp See Usage Guidelines on page 66. The namespace under which this class resides must end with the name of the component which it is customizing.cydsn). For example. it is possible to precompile the component customizers for a library.Bar.1.1. the directory will be located at: Documents and Settings/user_name/Local Settings/Application Data/ Cypress Semiconductor/cydsfit/1. and most component authors will not need it.Data.0.Forms.dll" To specify . You will have to type in the relative path.Windows.7 Specify Assembly References You will be able to specify references to additional external DLLs for the customizers. *G 65 . 7. copy it into the library directory structure. the legal namespaces under which the "CyCustomizer" class could reside are: Foo. For example. 7.

PSoC Creator will refuse to build a new customizer assembly if a precompiled customizer assembly for a project already exists.3. To avoid unintended substitutions in the source code. The precompiled component customizer is named _project_. and then delete any precompiled component customizer assembly in the project folder. all instances of the namespace within the customizer source are replaced. If resources (. 1. all the components in a library should have a common distinct prefix. To create a precompiled component customizer assembly for a library.3. Delete any existing precompiled component customizer assembly from the project (see steps below). the component customizer used will be silently out-of-date. 7. Remove the precompiled component customizer assembly (named _project_.NET does a better job distinguishing between strongly named assemblies. To remove a precompiled component customizer assembly from a library. To reduce confusion. In addition. For these reasons. ensure that each externally referenced assembly has a distinct name.2 Use Distinct External Dependencies . 1. 66 PSoC Creator Component Author Guide. 7. Of course. 2. which holds the code to be shared.Name. Note The existence of a precompiled component customizer will bypass the source files. do the following. So two different assemblies with the same name can get confused.Customizing Components library. Exit from PSoC Creator. and the delete from disk will fail). A and B) want to share code. and only if you are sure that the component customizers are unlikely to change.3 7. create a new component called Common. only use this feature if performance requires it.dll) from the project (but not from disk -. do the following. 7. *G . When a component is renamed or imported. a precompiled customizer is opened automatically. If the source files change. Add the Advanced Customizer toolbar to PSoC Creator. Experience shows that .3.. Document # 001-42697 Rev.3 Use Common Component To Share Code If two customizers (e. not the file location.g. they too use that same name to identify the compiled resources.resx) files are used. which will prevent the project from being renamed or the customizer from being updated.NET resolves external assembly dependencies based on the assembly name. if you import A or B. since the precompiled customizer assembly will always be used.Company.1 Usage Guidelines Use Distinct Namespaces The leafname of the namespace identifies the component to which the customizer source applies. you also need to import Common.dll and is visible in the Workspace Explorer at the top level of the project. and to allow shared source (where one component can use common utility routines defined in another component in the same library). Click the Build and Attach customizer button. 2.it is open. To avoid problems with external dependencies. for example: Some. 3.

Provides access to write values to an instance The interface includes methods for writing new parameter values. This allows for upgrades to the interface without breaking existing customizers. Query allows for querying but not modifying anything in PSoC Creator. and hooks to obtain additional interfaces. find out information about the instance.only the values of the parameters can be changed. and creating parameter editors. 7. The following sections list and summarize the various customization interfaces. These interfaces provide methods to read/write parameter values.1 System Interfaces This section describes the system interfaces used by customization interfaces. setting custom data. ICyInstQuery_v1 ICyInstEdit_v1 PSoC Creator Component Author Guide.5 Interfaces The customization support defines two sets of interfaces:   System interfaces used by customization interfaces Customization interfaces implemented by component authors The interfaces are named with the version number concatenated to the end of the name.Net types to provide a stable and low complexity interface. For in depth documentation. refer to the PSoC Creator Customization API Reference Guide (customizer_api. Provides read only access to information about an instance. and discover connectivity information.chm file. The following table contains a brief summary of the system interfaces.Customizing Components 7. Edit allows the customization inferfaces to update/modify various aspects of the component. PSoC Creator implements the system interfaces to provide access to PSoC Creator internal data structures using native C# and .4 Customization Examples See the example project located in the following directory: C:\Program Files\Cypress\PSoC Creator\1. This includes the associated terminal shapes. In general. parameter information.5. Document # 001-42697 Rev.0\PSoC Creator\examples\ customizers\SimpleDialogCustomizer. located in the same directory as this Component Author Guide). This includes general instance information. or to ask for information about items connected to a terminal on an instance. Allows customizers to alter the basic shapes based on the master symbol of an instance. custom data access. Table 7-1. Allows for querying of shape information off an instance's master symbol. It is not possible to add or remove parameters -. System Interfaces Summary Interface ICyTerminalQuery_v1 ICyTerminalEdit_v1 ICySymbolShapeQuery_v1 ICySymbolShapeEdit_v1 Description Used to ask for information about terminals on an instance. Terminal shapes don't use the shape query or shape edit interfaces.cydsn\ 7. Used for editing terminals on an instance. *G 67 . there are two types of system interfaces: query and edit.

only the errors associated with them can be set. it can be stored in hidden parameters on the instance. *G .e. It is subject to change in later releases. Implementers of this interface will be called to generate custom Verilog code based on a component instance. Allows for altering what an instance on a schematic "looks" like (i. If persistent data is needed.. It is not possible for the client using this object to carry over information from one invocation to the next. The following table contains a brief summary of the customization interfaces. Components that generate or manipulate clocks can make their clock information available to other components in the system. Prototype support for Express-style components. The values of the parameters cannot be changed. A new instance of the user-provided customizer is created every time it is called. Customize the tool-tip text that appears when users hover over a component instance. Implemented by instance customizers that are interested in controlling how the instance's API is generated. Its sole purpose is to prototype Expressstyle content support..2 Customization Interfaces This section describes the customization interfaces implemented by component authors. It is subject to change in later releases.5. Document # 001-42697 Rev.. If both versions are implemented. Table 7-2. This interface should not be used. Allows for querying of design-wide information. Updated from version 1. shapes and terminals it contains) through code. Implement this interface to take control of the "Customize. version 2 will be used. Implement this interface if you wish to store custom information on your component. The CustomizeAPIs method in version 2 has a slightly different signature than in version 1. The methods in this interface allow customizer developers to indicate that their customizer is sensitive to changing information and they need to be invoked when the data changes. This custom data is available to all other customization interfaces via its ICyInstQuery_v1 of ICyInstEdit_v1 parameter.Customizing Components Table 7-1. System Interfaces Summary (continued) Interface ICyInstValidate_v1 Description Provides access to validate parameters on an instance and then set their resulting errors. This may be used in conjunction with the ICyImplementationSelector_v1 interface to select between multiple potential component implementations. ICyExpressMgr_v1 ICyDesignQuery_v1 ICyResourceTypes_v1 7. Provides access to the names of certain resources supported by some devices." context menu implementation for an instance. ICyCustomData_v1 ICyExpressComponent_v1 ICyShapeCustomize_v1 ICyVerilogCustomize_v1 ICyAPICustomize_v1 ICyAPICustomize_v2 ICyToolTipCustomize_v1 ICyClockDataProvider_v1 ICyDesignClient_v1 68 PSoC Creator Component Author Guide. Customization Interfaces Summary Interface ICyInstValidateHook_v1 ICyParamEditHook_v1 Description Implement this interface to be able to validate the parameter values on an instance in code whenever a change is made to the instance.

5. I2C).g. 7. This is provided via a series of customization interfaces. a fixed function block versus a softimplementation). 7.NET objects (bool. and an index) and returns the frequencies of the clock that drives the terminal. Document # 001-42697 Rev.3.. uint. sbyte. Implement this interface to take create instance specific notices to be added to the notice list inside of PSoC Creator. *G 69 . string).1 ICyTerminalQuery_v1 Has two methods called GetClockData.3.4 Clock API support Certain component APIs need access to the initial clock configuration in order to properly function (e. float. #define BCLK__BUS_CLK__HZ value #define BCLK__BUS_CLK__KZ value #define BCLK__BUS_CLK__MHZ value PSoC Creator Component Author Guide.5. int. and an index and returns the clock frequency of buried clocks. a terminal name.3 Clock Query in Customizers PSoC Creator provides a robust mechanism for component authors to provide and query for clockrelated information. PSoC Creator will expose the initial configuration of the following via #defines in cyfitter.g.h. byte.5.2 ICyClockDataProvider_v1 Components that generate or manipulate clocks can provide their frequency information to PSoC Creator and it will automatically be accessible to the GetClockData methods. Used to convert items in the args array passed to CyExprEvalFunc delegates into . Customization Interfaces Summary (continued) Interface ICyImplementationSelector_v1 Description Used for components that may have more than one potential implementation available (e.. short. ICyExprTypeConverter ICyExprEval_v1 ICyDRCProvider_v1 7. 7.5. The second takes an "instance path". Used to create new expression system functions using C#. One takes two parameters (a terminal name. ushort.Customizing Components Table 7-2.

*G . Document # 001-42697 Rev.Customizing Components 70 PSoC Creator Component Author Guide.

8. The effects of the parameter changes are visible in realtime as they are applied. Adding Tuning Support Tuning support is a highly advanced feature that is used for a few limited components. Parameter values are written from the PC down to the chip at the user’s request. *G 71 . that require the ability for the user to tune the component while it is in the design. PSoC Creator Component Author Guide. The second API is implemented by PSoC Creator and it provides a communication mechanism that a tuner uses to communicate with the PSoC device. Communication to the device is done using an I2C or EZ I2C component in the end user’s design. Document # 001-42697 Rev. It is the responsibility of the user to set up this two-way communication channel using a communication protocol that both the tuning framework and the tunable component support. One API is implemented by component authors and it is the launching point for a component tuner. Tuning requires communication between the firmware component and the host application. The tuning application runs on a PC that is running PSoC Creator and it displays values as they come from a PSoC device. It is not possible for PSoC Creator to automatically set up a communication channel for the user’s design because it is not safe to make assumptions about what communication is available or how the user is using the communication components for additional purposes. PSoC Creator supports this requirement by providing a flexible API that component authors can use to implement tuning for their component. The framework primarily consists of two APIs. This is an iterative process in order to get the best possible results out of the device.8. such as CapSense®.1 Tuning Framework The tuning framework is a general purpose framework set up to support tuning by any component. Tuning is typically done with a GUI that displays scan values on the various inputs and allows the user to set new tuning parameter values. The firmware sends scan values to the GUI and the GUI sends updated tuning parameters down to the firmware.

PSoC Creator passes the tuner a communication object that implements the TunerComm API. PSoC Creator launches the tuner as a non-modal window so that the user can do other things (such as debugging) while the tuner is running. For in depth documentation. The application launching the tuner is responsible for implementing each of the functions for their desired communication protocol. The tuner uses this object to read and write from the device. TunerLaunch API PSoC Creator TunerComm API Component I2C MP3 PSoC 8. The contents of the data being communication are opaque to PSoC Creator. PSoC Creator interacts with the PSoC device using I2C and the MiniProg3. The component’s tuner uses the TuningComm API to read and write to the device. The TunerComm API implements a data communication channel between the tuner GUI and the component firmware on the chip.3. The following sections list and summarize the various tuning interfaces. 72 PSoC Creator Component Author Guide. It is up to the component tuner to make sure that the GUI and firmware agree on the contents of the data being passed.2 Architecture The following diagram shows the PSoC Creator tuning framework. *G . Document # 001-42697 Rev. refer to the PSoC Creator Tuning API Reference Guide (tuner_api. 8.chm file. Any component that implements the LaunchTuner API is considered a tunable component. 8. PSoC Creator launches tuning for a component using the TunerLaunch API. located in the same directory as this Component Author Guide).1 LaunchTuner API The LaunchTuner API is implemented by the component and is called by PSoC Creator when the user selects the Launch Tuner option on a component instance. The TunerComm API is implemented by PSoC Creator and is used by a tuner to communicate with the PSoC device using a supported tuning communication channel.3.Adding Tuning Support 8.2 Communications API (ICyTunerCommAPI_v1) The communications API defines a set the functions that allow the tuner GUI to communicate with the firmware component without knowing any specifics about the communication mechanism being used.3 Tuning APIs PSoC Creator defines two APIs for use by component authors to support tuning: LaunchTuner and TunerComm.

Adding Tuning Support 8.chm file.4 Passing Parameters Parameters are passed between PSoC Creator and the tuner using the CyTunerParams class which is a simple wrapper class for name/value pairs. the TunerComm API provides a set-up method. To support this abstraction. PSoC Creator does not support source-based tuners. Refer to the PSoC Creator Tuning API Reference Guide (tuner_api.5 Component Tuner DLL The component tuner code should be included with the component as a tuner dll. 8. PSoC Creator Component Author Guide.7 Launching the Tuner PSoC Creator will provide a menu item that launches the tuner for a component instance. the communication setup between the tuner and the device is owned by the component’s end user. *G 73 . Therefore. The component tuner should call this method to initiate communication configuration. Add a “Tuner DLL” file to the component using the Add Component Item dialog. located in the same directory as this Component Author Guide). the tuner must be compiled outside of the tool and supplied as a dll.6 Communication Setup As described previously in this chapter. Document # 001-42697 Rev. 8. This menu item is only available on the component instance context menu since it only makes sense within the context of a particular tunable component instance. A component tuner has no knowledge of how this communication will be set up. 8.

the user’s design must be built and programmed into the device. the user’s main function will need to contain “traffic cop” code that facilitates data transfer between the I2C and tunable component. } // If the PC has completed writing new parameter values // then pass those along to the component for processing if (buffer write complete) { CapSense_ProcessParameters(tuning_data). 8.c. The following pseudo code shows an example main.9 Component Modifications To support tuning the component’s firmware and APIs must be built to support tuning. // Start the communication component // Start the tunable component // Configure I2C to manage buffer I2C_SetBuffer(tuning_data). CapSense_Start(). 8. This will likely be implemented by using a byte of data in the buffer for read and write enables. I2C_Start(). main() { struct tuning_data { // this data is opaque to PSoC Creator but known to the component } tuning_data.. The firmware that is built when in tuning mode will be aware of this structure so that it can process parameters correctly.8 Firmware Traffic Cop The user’s design will contain a main. The exact structure of this struct is decided at build time by the component.9. } } } This main function relies on a way to synchronize the reads and writes between the chip and the host PC. *G .) { // If there the data from the last push has been consumed // by the PC then go ahead and fill the buffer again.c file that implements the user’s firmware design. Document # 001-42697 Rev. for (. 74 PSoC Creator Component Author Guide.Adding Tuning Support 8.1 Communication Data Data to/from the chip will be communicated via a shared c struct that contains fields for the scan values and the tuning parameter values. In order to support tuning. if (buffer read complete) { CapSense_FillBuffer(tuning_data). After the component is in tuning mode. It is likely that users will not want the overhead of tuning support in their final design so it is required that the component configuration dialog give the user an option to put the component into tuning mode.

InitParams(params).GetParameters()). } // Creator calls this method to retrieve the new // values of all parameters public override CyTunerParams GetParameters() { return(m_form. The following is example code for a tuner (the API documentation provides more details): public class MyTuner : CyTunerProviderBase { MyForm m_form. ICyTunerComm comm. } public override void LaunchTuner(CyTunerParams params. Document # 001-42697 Rev.Adding Tuning Support 8. PSoC Creator will call GetParameters() to get the new parameter values which it will then store on the component instance.SetComm(comm). ShowDialog(). // When this method exists. PSoC Creator Component Author Guide. // a custom GUI public MyTuner() // Tuner constructor just creates the form { m_form = new MyForm().ShowDialog(). CyTunerGUIMode mode) { m_form. the tuner creates a custom GUI (MyForm) and then calls show dialog on this. // Set up the form m_form. Since this tuner is being run its own thread.10 A simple tuner The class that implements the tuner has full control over how it will operate. LaunchTuner resturns to Creator m_form. } } In this code. Once the method call returns. *G 75 . PSoC Creator will call the LaunchTuner method and then wait for it to return. it is safe for it to call the blocking call. without fear of hanging PSoC Creator.

Document # 001-42697 Rev.Adding Tuning Support 76 PSoC Creator Component Author Guide. *G .

Adding Bootloader Support This chapter describes how to provide bootloader support for a component.2. each with implementations of the necessary bootloader functions.1.1 Firmware For a component to support bootloading. Document # 001-42697 Rev. For more information about the PSoC Creator bootloader system. *G 77 . For more information about source code and implementing functions.9. These functions are used by the bootloader for setting up the communications interface and relaying packets back and forth with the host.2 Functions The following functions need to be implemented in the component to support bootloading:      CyBtldrCommStart CyBtldrCommStop CyBtldrCommReset CyBtldrCommWrite CyBtldrCommRead The following sections provide function definitions. there are two general areas to modify:   Firmware Customizer Bootloader Interface 9. To provide bootloader support in a component.1. 9. refer to the PSoC Creator System Reference Guide.1. all must be guarded for conditional preprocessor inclusion. This guard is: #if defined(CYDEV_BOOTLOADER_IO_COMP) && (CYDEV_BOOTLOADER_IO_COMP == CyBtldr_`@INSTANCE_NAME`) //Bootloader code #endif 9.1 Guarding Because there can be multiple bootloader supporting components in the design at once. see the Adding API Files chapter on page 59. it must implement five functions described in Section 9. PSoC Creator Component Author Guide.

uint16 *count.3 void CyBtldrCommReset(void) Description: Parameters: Return Value: Side Effects: Forces the selected communications component to remove stale data. None Parameters: 78 PSoC Creator Component Author Guide.2. 9. In many cases. In many cases. *G . Document # 001-42697 Rev. Once the write is done count is updated with the number of bytes written.1.Adding Bootloader Support 9. If the write completes early it should return a success code as soon as possible. uint16 size. this is just a call to the existing function `@INSTANCE_NAME`_Stop() None None Stops up the communications component and does any tear down necessary to disable the communications component. 9. None None Clears any cached data in the communications component and sets the component back to a state to read/write a fresh command. component should wait before indicating communications timed out Return Value: Side Effects: CYRET_SUCCESS if one or more bytes were successfully written. 9. CYRET_TIMEOUT if the host controller did not respond to the write in 10 milliseconds * timeOut milliseconds.1. uint8 *data – pointer to the buffer containing data to be written uint16 size – the number of bytes from the data buffer to write uint16 *count – pointer to where the comm.2. This is used when a command has been interrupted or is corrupt to clear the component’s state and begin again.1. The timeOut parameter is used to provide an upper bound on the time that the function is allowed to operate. this is just a call to the existing function `@INSTANCE_NAME`_Start() None None Starts up the communications component and does any configuration necessary to allow data to be read and/or written by the PSoC.2.2 void CyBtldrCommStop(void) Description: Parameters: Return Value: Side Effects: This function will stop the selected communications component.4 cystatus CyBtldrCommWrite(uint8 *data.2. uint8 timeOut) Description: Requests that the provided size number of bytes are written from the input data buffer to the host device.1 void CyBtldrCommStart(void) Description: Parameters: Return Value: Side Effects: This function will start the selected communications component. component will write the count of the number of bytes actually written uint8 timeOut – amount of time (in units of 10 milliseconds) the comm. If the write was not successful before the allotted time has expired it should return an error.1.

If the read was not successful before the allotted time has expired it should return an error. For components that can be configured to meet this requirement.chm file.” It contains a single method that is used by the bootloader to determine whether the current configuration of the component is bootloader compatible. see the Customizing Components chapter on page 63. PSoC Creator Component Author Guide. *G 79 . uint16 *count. as follows:  ICyBootLoaderSupport This interface is described in the the PSoC Creator Customization API Reference Guide (customizer_api.5 cystatus CyBtldrCommRead(uint8 *data. None Parameters: 9. uint8 timeOut) Description: Requests that the provided size number of bytes are read from the host device and stored in the provided data buffer. If the read completes early it should return a success code as soon as possible. component will write the count of the number of bytes actually read uint8 timeOut – amount of time (in units of 10 milliseconds) the comm.2. public interface ICyBootLoaderSupport { CyCustErr IsBootloaderReady(ICyInstQuery_v1 inst).Adding Bootloader Support 9.3 Customizer Bootloader Interface The bootloader requires that the communication component is configured for both transfer in and out of the PSoC device. For more information about customizers. uint16 size. located in the same directory as this Component Author Guide). under “Common Interfaces. any instance placed in the design will be shown as an option for the bootloader IO component in the Design-Wide Resources System Editor. The timeOut parameter is used to provide an upper bound on the time that the function is allowed to operate. component should wait before indicating communications timed out Return Value: Side Effects: CYRET_SUCCESS if one or more bytes were successfully read. } When the component is bootloader ready. The implementation of the single method within the customizer only needs to validate the current configuration of the component to make sure the settings are compatable with bi-directional communication. CYRET_TIMEOUT if the host controller did not respond to the read in 10 milliseconds * timeOut milliseconds. Document # 001-42697 Rev. there is an interface that can be implemented by the customizer that will inform PSoC Creator of this support.1.1. Once the write is done count is updated with the number of bytes written. uint8 *data – pointer to the buffer to store data from the host controller uint16 size – the number of bytes to read into the data buffer uint16 *count – pointer to where the comm.

Adding Bootloader Support 80 PSoC Creator Component Author Guide. Document # 001-42697 Rev. *G .

The main requirement is that a PDF file must have the same name as the component in order to be viewed from the Component Catalog. select Create New to allow PSoC Creator to create a dummy file. Finishing the Component This chapter covers the various steps involved with finishing the component. Select the Document Files icon under the Misc category from the templates. Note This process applies to any number of miscellaneous files you wish to add to the component. including:    Add/create datasheet Add debug XML file Build the project 10. you can convert that file into PDF. PSoC Creator Component Author Guide. Click Add Existing to select an existing file to add to the component. and type the name of the PDF file to add in Item name. The Add Component Item dialog displays.1 Add/Create Datasheet You can create component datasheets using MS Word. or XML and add it to the component. Then. Right-click on the component and select Add Component Item. 2.10. Click on a different template icon to add a different file type. The item displays in the Workspace Explorer and opens as a tabbed document in PSoC Creator. 1. HTML. FrameMaker. *G 81 . Document # 001-42697 Rev. or any other type of word processing program. 3.

2 Add/Create Debug XML File PSoC Creator provides an optional mechanism for creating new debugger tool windows for any component.h. To enable this feature on a specific component. (string) desc – A description of the block (string) visible – Specifies whether the contents of the block are displayed (string evaluate to bool) Memory Represents a contiguous block of memory used by the component     name – The name of the block of memory (string) desc – A description of the block of memory (string) address – The address that the memory starts at (string evaluate to uint) size – The number of bytes in the block (string evaluate to uint) Register Represents a register used internally by the component     name – The name of the register (string) desc – A description of the register (string) address – The address that the register is located at (string evaluate to uint) bitWidth – The number of bits in the register (string evaluate to uint) Field A portion of a register that has specific meaning   name – The name of the field (string) desc – A description of the field (string) 82 PSoC Creator Component Author Guide. The Add Component Item dialog displays. 3. Select the Debug XML File icon under the Misc category from the templates.2. copy it over the file in the project. Right-click on the component and select Add > New Component Item. or a #define from cydevice. The item displays in the Workspace Explorer and opens as a tabbed document in the PSoC Creator Code Editor.1 XML Format The following are the major elements of the debug XML file.h. This information can consist of any blocks of memory used or individual registers that are important to the component. Addresses must be an actual address. Block Represents a set of related registers/memories    name – The block name.Finishing the Component 4. cydevice_trm. *G .h. will be appended to all sub items. Document # 001-42697 Rev. or cyfitter. select Create New to allow PSoC Creator to create a dummy file. you add an XML description of the component. 2. 10. 1. Click Add Existing to select an existing file to add to the component. the name becomes the same as the component. The names of items in the XML documents cannot contain spaces. 10. If you created a file outside of PSoC Creator.

0" encoding="us-ascii"?> <deviceData version="1" xmlns="http://cypress.2.w3.com/xsd/cydevicedata" xmlns:xsi="http://www. *G 83 .org/2001/XMLSchema-instance" xsi:schemaLocation="http://cypress.xsd"> <block name="`$INSTANCE_NAME`" desc=""> <block name="UDB" desc="" visible="!`$FixedFunction`"> <register name="CTL_REG" address="`$INSTANCE_NAME`_UDB_sCTRLReg_CTL_REG" bitWidth="8" desc=""> <field name="STAT" from="7" to="3" access="R" desc="”> <value name="VALID" value="0" desc="" /> <value name="INVALID" value="1" desc="" /> </field> <field name="ACT" from="2" to="0" access="RW" desc="”> </field> </register> <register name=" COUNT_REG" address="`$INSTANCE_NAME`_UDB_sCTRLReg_COUNT_REG" bitWidth="16" desc=""> </register> <register name="MASK_REG" address="`$INSTANCE_NAME`_UDB_sCTRLReg_MASK_REG" bitWidth="8" desc=""> </register> </block> <block name="HW" desc="" visible="`$FixedFunction`"> <register name="CTL_REG" address="`$INSTANCE_NAME`_HW_sCTRLReg_CTL_REG" bitWidth="16" desc=""> </register> </block> <memory name="memory" address="`$INSTANCE_NAME`_UDB_sCTRLReg_MASK_REG" size="256" desc=""> </memory> </block> </deviceData> PSoC Creator Component Author Guide.com/xsd/cydevicedata cydevicedata.2 Example XML File The following is an example debug XML file.Finishing the Component    from – The high order bit for the field (string evaluate to uint) to – The low order bit for the field (string evaluate to uint) access – The type of access available for the register (string) Value A specific value that has meaning to a Register Field    name – The name of the value (string) desc – A description of the value (string) value – The value (string evaluate to uint) 10. All the information needs to be added within the Block element: <?xml version="1. Document # 001-42697 Rev.

Architecture The Architecture element is used to optionally specify the architecture: PSoC3 or PSoC5. enter the same name as the component with a cystate extension (for example.1 XML Format The following are the major elements of the cystate file. Select the Misc. and notes if a component is used with incompatible versions of silicon. If used. 2. you must also provide a ComponentState element. The item displays in the Workspace Explorer and opens as a tabbed document in the PSoC Creator Code Editor. Note. ComponentStateMap The ComponentStateMap element is the root element in which you must include a ComponentState element (used as global default). The Add Component Item dialog displays. Right-click on the component and select Add > New Component Item. Families The Families element is used to optionally specify an architecture family: 3A or 5A. Warning. Document # 001-42697 Rev. 1. MessageType A MessageType element is used to specify the type of DRC. then no DRCs will be generated. The names of items in the XML documents cannot contain spaces. It can be one of the following values: None. SiliconRevision The SiliconRevision element is used to optionally specify the silicon revision: ES1. for example. *G . File icon under the Misc category from the templates. Click Add Existing to select an existing file to add to the component. You can also provide a ComponentState element and also include zero or more Families elements. errors. 84 PSoC Creator Component Author Guide. You can also provide a ComponentState element and also include zero or more SiliconRevision elements. For the name. 3.3 Add/Create Compatibility XML File PSoC Creator provides an optional mechanism for adding compatibility information to your components.cystate) 4. You can also optionally provide a message string. If you do not include a cystate file. This feature can be used to generate DRC warnings. or ES3. for example. cy_clock_v1_50. ES2. select Create New to allow PSoC Creator to create a dummy file. 10.Finishing the Component 10. or Error.3. for example. ComponentState The ComponentState element is used to provide a MessageType element.

When a component project is built. PSoC Creator Component Author Guide.3. you must instantiate the component in a design in order to build and test it. The minimum required information is the default level rule. <?xml version="1. *G 85 .cystate File The following is an example cystate file.2 Example . </Message> </ComponentState> <Architecture Name="PSoC3"> <Families Name="3A"> <ComponentState> <MessageType>None</MessageType> </ComponentState> </Families> </Architecture> <Architecture Name="PSoC5"> <Families Name="5A"> <ComponentState> <MessageType>None</MessageType> </ComponentState> <SiliconRevision Name="ES1"> <ComponentState> <MessageType>Error</MessageType> </ComponentState> </SiliconRevision> </Families> </Architecture> </ComponentStateMap> 10. After a build.4 Build the project When you’ve added and completed all the necessary component items for the component. the build directory will contain all aspects of the component that the component author has specified via the project manager. including the family-specific portions. Document # 001-42697 Rev.Finishing the Component 10. all portions of it are built.0" encoding="utf-8"?> <ComponentStateMap Version="1"> <!--Default component state--> <ComponentState> <MessageType>Warning</MessageType> <Message>Component has not been tested for this device.

Document # 001-42697 Rev.Finishing the Component 86 PSoC Creator Component Author Guide. *G .

using the status register in this manner removes it from the pool of resources inside the UDB. Document # 001-42697 Rev. it is sometimes tempting to allow both edges of a clock to be used. 11. As expected. 11. The first way is to use the PLD macrocells as synchronizers.11.1. clocking architectures must be completely understood and designed with the limitations and device characteristics firmly in mind.1 Clocking When using the clocking resources internal to the PSoC device. all designs should use only posedge (Verilog PSoC Creator Component Author Guide. However. and datapath internal registers. for instance the clock source to be used is not a 50% duty cycle. These registers include the status. While this is sometimes acceptable in certain situations. however. This clock is the main clock for the implemented function. this is not universally true. Best Practices This chapter covers general best practices to consider when creating components.1. The second way is to allocate the status register as a 4-bit synchronizer. *G 87 . There are many other resources that can and will be contrived using clock sources other than those internally available in the chip. the setup and hold timing budgets may be violated resulting in unexpected or unwanted results. If. it becomes very dangerous in others. The first of these is the bus clock (bus_clk).2 Component Clocking Considerations When considering what clock should be used to clock a particular function in a design. there may exist at least two clock domains.1 UDB Architectural Clocking Considerations Inside of each UDB. there are several things to keep in mind. This clock may have its origin entirely outside the PSoC internal clocking structure. used by the CPU to access the registers internal to the UDB. As with any digital system. The second class of clock domain is controlled by a “user” clock. control. The status register can be configured to allow its 8 internal flip-flops to become 4 dual flip-flop synchronizers. Many of the digital resources available in the PSoC device can be clocked using the internal clocks of the device. To prevent these types of problems. It is both of these cases that have to be considered when designing components for use in the PSoC device. To avoid metastable conditions in the UDB. There are a couple of ways that this can be accomplished with resources internal to the UDB. synchronization flip-flops may be necessary whenever a signal crosses either clock domain boundary. including:       Clocking Interrupts DMA Low Power Support Component Encapulation Verilog 11.

Best Practices instances) clocking and only connect clock pins of components to the positive sense of the clock. there is a possibility of problems. Eventually. The timing analysis of signals crossing clock domain boundaries is necessary in all circumstances.4 UDB to Input/Output Clocking Considerations The clocking structure available within the UDB that allows for global. However. This makes the I/O timing problem more complex by creating long clock arrival times resulting in long set-up times. It is therefore imperative that metastable states be avoided. 11.1. any output registers that are not clocked by bus_clk must use UDB resources before being sent to the output. Some of those blocks have built-in re-synchronizers. These signals have to be analyzed to ensure that they meet the required timing. Additionally. 11. it may be necessary to validate their phase relationships to the region that they enter. after some time. this state will resolve to a stable state of either a ‘1’ or a ‘0’. Long combinatorial paths between flip-flops in a single clock domain.5 Metastability in Flip-Flops In any discussion of clocking for digital circuitry. In combinatorial circuits. The GPIO registers have access only to bus_clk and are not clock aligned with any external clock that a function may be using. Any time a signal crosses the boundary between the UDB array and one of these other elements.3 UDB to Chip Resource Clocking Considerations Signals that enter or leave the UDB array are not always intended for the I/O pins of the device. *G . Because of this limitation. these external clocks do not come directly via the clock tree. However. Metastability can be defined as a period of time when the output of a flip-flop is unpredictable or is in an unstable (or metastable) state. Paramount in that discussion should be a definition and explanation of metastable states of flip-flops. There are several conditions that can result in metastable conditions. If an event must happen on the negative edge of a clock. but others do not. a metastable state is possible if not probable. In general if the set-up time (Tsu) or hold time (Th) of the flip-flop is violated. Contrarily. those outputs may cause glitches in the circuits that it drives.1. This results in a very long clock to out path. it is necessary to understand the consequences of the clocking architecture. Document # 001-42697 Rev. 11. In sequential circuits. Any signal can be used by the UDB as an external clock signal. bus_clk. DMA. Clock skew between flip-flops in a single clock domain Any one of these (or other) situations may cause a metastable condition. even for signals that are synchronous to the internal clocks. many of those signals connect to other resources on the PSoC such as fixed function blocks. signals sent to and/or received by the UDB must receive special consideration. those glitches result in hazard conditions that could affect the storing of data in registers and the decision processes for state machines. that can be accomplished by providing a 2X multiple of the needed clock to clock the circuitry appropriately. They are routed through long paths before they can enter the clock tree. that resolution may not be quick enough for circuitry that is dependent upon the output to correctly evaluate the final result.1. Because of this limitation. or interrupts. 88 PSoC Creator Component Author Guide. and user clocks is not universally available to the rest of the PSoC architecture. these conditions include:    Signals that cross a clock domain boundary. A synchronous signal that is shifted by some amount may not satisfy the requirements for the timing in the destination circuitry.

8 Synchronous Versus Asynchronous Clocks Clocking architectures often contain multiple types of clocks. If they are already a derivative of that clock. The enable signal can also be either synchronous or asynchronous to bus_clk. This is the clock that is referred to as bus_clk. Tcomb is the combinatorial delay of the intervening circuitry. the following equation must be true: Tco + Tcomb + Tsu < Tcycle Equation 1 Tco represents the clock to out time of the driving flip-flop. That primitive is the cy_psoc3_udb_clock_enable. a complete understanding of the timing from clock to output of the component must be understood and communicated.6 Clock Domain Boundary Crossing There are several storage elements internal to the PSoC 3/5 UDBs.1. and a parameter to specify the intended synchronization behavior for the clock result (sync_mode).Best Practices 11. These two signals are then connected to the primitive and the user selects either synchronous or asynchronous mode. If the ClkIn is the bus_clk. If signals need to be interfaced to the MPU but are controlled by clocks that are asynchronous to bus_clk. If this is not possible or desirable.1. we define the master system clock as that clock (or some derivative of it) that the MPU uses as its core clock. Document # 001-42697 Rev.1. Once these have been done. they are more easily handled.7 Long Combinatorial Path Considerations When long combinatorial paths are created in a design. a clock output (clock_out) that will drive the UDB components. However. *G 89 . the total delays involved must be less than the cycle time of the clock. Each one of these is accessible via the CPU bus_clk. If these long paths are contained completely within a component. 2) global clock (SrcClk). They are also accessible via some other clock source that is the primary clock for the circuit (ClkIn).9 Utilizing cy_psoc3_udb_clock_enable Primitive There is a means available in PSoC Creator accessible by instantiation of a Verilog primitive that can help with the complexities of clocking and handle some clock conditioning automatically. signals leaving a component should be driven by a flip-flop to avoid problems. Tsu is the set-up time of the next flip-flop stage. then the task for a designer is to ensure that there are no long combinatorial path problems or problematic skews (discussed earlier). For our purposes. signals that are interfaced to the MPU should be synchronized with the bus_clk signal.1. there may still remain situations where excessive skew is possible or long combinatorial paths exist. they may need to be synchronized before being presented to that interface. Therefore. we can be assured that we have a single clock domain and worries about clock domain crossing can be eliminated. the fitter in PSoC Creator will PSoC Creator Component Author Guide. 11. To avoid such conditions. The cy_psoc3_udb_clock_enable has inputs for an enable (enable) and clock (clock_in). 11. or 3) external clock (ExtClk). The use of this primitive can aid in handling clocks that are synchronous as well as asynchronous. 11. it is possible that set-up time for a subsequent storage element is violated. Some of these clocks may be synchronous to a master system clock and some of them may be asynchronous to that clock. To best avoid metastability problems. There are some primitive components that are available in PSoC Creator that can help with that task and are detailed in the following sections. In other words. The clock_in signal can be either a global clock or a local clock and can be either synchronous or asynchronous to bus_clk. This clock source can be selected from several places: 1) CPU bus_clk.

.1. 90 PSoC Creator Component Author Guide. . These double registers are taken from the UDB macrocells. *G .clock (my_clock_input).enable (my_clock_enable). The rule set used when mapping the clock/enable to the UDB is listed in the following table: Inputs clock_in Global Sync Global Async Local Sync Local Async Global Sync Global Async Local Sync Local Async Global Sync Global Async Local Sync Local Async Global Sync Global Async Local Sync Local Async en Sync Sync Sync Sync Async Async Async Async Sync Sync Sync Sync Async Async Async Async sync_mode Yes Yes Yes Yes Yes Yes Yes Yes No No No No No No No No UDB Translation Mode Level Edge Edge Level Edge Edge Level Level Level Level Level Level Level Level Enable En ClkIn & En Sync(ClkIn & En) Sync(En) Sync(ClkIn & En) Sync(ClkIn & En) En En En En Sync(En) Sync(En) Sync(En) Sync(En) Clock_out ClkIn SrcClk(ClkIn) bus_clk ClkIn SrcClk(ClkIn) bus_clk ClkIn ClkIn ExtClk(ClkIn) ExtClk(ClkIn) ClkIn ClkIn ExtClk(ClkIn) ExtClk(ClkIn) Not allowed.sc_in (my_raw_signal_in). A typical instantiation of the cy_psoc3_udb_clock_enable primitive might look something like this: cy_psoc3_udb_clock_enable_v1_0 #(.clock_in (my_clock_input). however. Even though the primitive is a single bit wide. to instantiate four of these primitives and still consume a single register. It is possible. the Sync() function indicates that a double flip-flop has been used to synchronize the signal with clock_out.Best Practices determine the implementation necessary to obtain the requested clock behavior for the UDB elements and attach the appropriate signals to the mapped UDB results. 11. error during synthesis In the table above.clock_out (my_clock_out)). . it will consume an entire status register. .sync_mode (‘TRUE)) My_Clock_Enable ( . error during synthesis Not allowed. This primitive is a double flip-flop used to synchronize signals to a clock. A typical instantiation of the cy_psoc3_sync primitive might look something like this: cy_psoc3_sync My_Sync ( . These double flip-flops are created as an option to the UDB status register.sc_out (my_synced_signal_out)).10 Utilizing cy_psoc3_sync Component Another useful tool is the cy_psoc3_sync primitive. Document # 001-42697 Rev.

then a synchronizer is required. For example an interrupt that is targeted for the CPU may be designed to be sticky (clear on read) but that same request for DMA PSoC Creator Component Author Guide. Whether an interrupt is buried in a component or exposed as a terminal on the symbol should be based on whether the processing of the interrupt is specific to the application.11 Routed. the Tcycle is effectively cut in half. Any data signal in the UDB array routing can be used to generate an interrupt or DMA request.       11. Avoid clocking on negative edges of clocks. If a data signal will be asynchronous to a clock. for instance. a flip-flop is clocked with the positive edge and the resulting output is sent through some logic to another flip-flop that is clocked with a negative edge.1. Document # 001-42697 Rev. Do not take a global clock signal and create a combinatorial signal with it. Similarly do not send a global clock signal out of a component.12 Negative Clock Edge Hidden Dangers When designing with Verilog. we have determined that negedge statements should be avoided.1. *G 91 . Use a 2x clock instead. routed from an external signal and used as a clock input to support direct clocked functions (such as SPI Slave). When small amounts of data and frequent interaction with the CPU is required. A clock signal should be an input to the component and all clocked logic should be clocked on that single clock. 11. This allows the generation of a clock output at 1/2 or slower rate than the input clock. Drive all outputs from a component from a clocked element (flip-flop) to minimize the clock to out time. Avoid asynchronous reset and preset. the status register is the logical choice for generating interrupts.1. do not AND a clock signal to implement a gated clock. the output of a flip-flop clocked by another clock must be used.2 Interrupts The main role of interrupts is to interact with CPU firmware or a DMA channel. Mixing positive edge triggering and negative edge triggering commonly restricts the length of time a signal has to transverse it path. The timing of a global clock when it is used for anything other than as the clock input to a UDB element is not defined.Best Practices 11. Global and External Clocks There are three types of clocks available to the UDBs. For example. If it is specific the component should perform the necessary operations and then add merge banners for any application handling if appropriate. The status register and FIFO status registers are considered the primary means of generating these interrupts. 11. Global clock signals should not be output from a component. the highest frequency clock in the system external clock. From a timing perspective they will cause a combinatorial timing path from the reset/preset signal to the registered output to exist. To create a clock signal with a defined timing relationship. These include:    eight global clocks. This philosophy is also applicable to clocks that connect to instantiated components or schematic components. output from user-selectable clock dividers bus_clk. If there is a need to trigger on both edges of a clock. If.13 General Clocking Rules  Do not create clocks in the component. a double rate clock should be implemented and alternate positive edges should be used for triggering. The generation of interrupts or DMA request is specific to the design.

The status mode register (CFGx) provides mode selection for each bit of the status register. 11. *G . A status interrupt example would be a case where a PLD or datapath block generated a condition. By default the sc_io pin is in output mode and the interrupt may be driven to the routing matrix for connection to the interrupt controller. As shown in the figure above.Best Practices would not be appropriate because the design of the transaction descriptors would have to incorporate a separate descriptor to clear the request in addition to the transaction descriptors to process the data. Each bit of these registers has programmable connections to the routing matrix. such as a “compare true” condition. In this configuration. The register bit is cleared on a subsequent read by the CPU. interrupt generation is tied to the setting of status bits. The status register is read-only and it allows internal UDB state to be read out onto the system bus directly from internal routing. Sticky mode.1 Status Register A high level view of the Status and Control module is shown below. the register bit is set and stays set regardless of the subsequent state of the input. the MSB of the status register is read as the state of the interrupt bit. The selected clock for this 92 PSoC Creator Component Author Guide. is a mode which the input status is sampled and when the input goes high. The primary purpose of this block is to coordinate CPU firmware interaction with internal UDB operation. This allows firmware to monitor the state of UDB processing. Transparent read is a mode in which a CPU read of the status register returns the state of the routing input signal.2 Internal Interrupt Generation and Mask Register In most functions. which is a clear on read. that is captured by the status register and then read (and cleared) by CPU firmware. this feature is built into the status register logic as the masking (mask register) and OR reduction of status. Only the lower 7 bits of status input can be used with the built-in interrupt generation circuitry. 11.2. Document # 001-42697 Rev.2.

11. In these cases. f1_bus_stat. Document # 001-42697 Rev. The “bus” status is primarily intended for the system bus control for DMA interaction (when the system should read or write bytes). DMA transactions are the most reasonable method of transport. interrupts to control data flow should be performed using FIFO status registers.Best Practices block determines the sample rate. It loses its state across sleep intervals and is reset to 0x00 on wakeup. These FIFOs generate status that can be routed to interact with sequencers. The “bus” status is meaningful to the device system and should be routed to the DMA controller as a DMA request. The status register is nonretention. 11.2.2. f0_bus_stat). *G 93 . or an output buffer (datapath internally writes to the FIFO. two for each FIFO. The following diagram shows a highlevel view of the datapath module. or DMA requests.4 FIFO Status There are four FIFO status signals (f1_blk_stat.3 Retention Across Sleep Intervals The mask register is retention and will retain state across sleep intervals. that can be independently configured for direction as an input buffer (system bus writes to the FIFO. datapath internally reads the FIFO). The rate should be greater than or equal to the rate at which the status input signals are being generated. and the system bus reads from the FIFO). PSoC Creator Component Author Guide. When large amounts of data are being streamed or rapid burst are being transmitted or received. interrupts. f0_blk_stat.

This happens because the transmitter has exhausted the previously granted allotment before it gets the next update. 11. designers must employ a look-ahead indication of the FIFO status. Effectively.6 Buffer Underflow A receive port FIFO underflows when data falls below the low watermark and receives no data from the other end through the interface. The first two numbers reflect the amount of time required in getting the burst information built up at the transmitter. any port FIFO would indicate a satisfied status when the data path latency + status path latency + maximum burst transfer is less than being full.2. The last two numbers define the amount of time required to get the data moved across the interface from transmit FIFO to the receive FIFO over the particular link. software should program low watermark for each port FIFO. If the size of the buffer is less than or equal to 4 bytes. a decision should be made with regard to how much RAM will be used to store the data. To prevent underflow.2. To solve the overflow problem. an additional mandatory space after satisfied indication has to be provided in the port FIFO to avoid buffer overflows. This implies that the high watermark for a FIFO must be set equal to data path latency + status path latency + maximum burst.5 Buffer Overflow The receive FIFO should have enough space to accommodate all the pending (already scheduled or to be scheduled) data transfer to the particular port to avoid the potential overflows. *G . The buffer underflow depends on the maximum read rate of the port FIFO by the application logic. which is the sum of status update latency + status path latency + data scheduler latency and finally the data path latency. the watermark of status indication must be set high enough so that the transmitter responds to FIFO space available indication from the receiver before the application logic drains the port data from the FIFO. 11. Consider both buffer overflow and underflow in the implementation. and eventually goes empty even though the transmit FIFO has data to send for that port.Best Practices When implementing a buffer for transactions. The receive FIFO also absorbs the usually observed bursty nature of data on the interface. The time elapsed between the FIFO status indicating starving or hungry to get the data for that particular port is the total path latency. To prevent the underflow. a receive FIFO design and status check mechanism should ensure that there are no data losses due to overruns. the buffer should be implemented with the FIFO hardware. Thus. judiciously (that is. 94 PSoC Creator Component Author Guide. for example status starving or hungry from the receiver. This FIFO could also decouple the operating frequency of the user application logic from the frequency of the specific bus. Document # 001-42697 Rev. The buffering provided in the receive and transmit FIFOs allows the processing order of user application logic to be independent of the order of data transfer on the bus. Ideally. large enough).

The DMA handler and associated APIs are outlined in DMA component datasheet. PHUB contains logic that performs arbitration between DMAC and the CPU for access to PHUB’s downstream spokes. The PHUB contains a DMA controller (DMAC) that can be programmed to transfer data between system elements without burdening the CPU.Best Practices 11. *G 95 .3 DMA The Peripheral HUB (PHUB) is a programmable and configurable central hub within a PSoC 3 and PSoC 5 device that ties the various on-chip system elements together utilizing standard Advanced Microcontroller Bus Architecture (AMBA) high-performance bus (AHB). PHUB. and that the DMAC arbitrates between multiple DMA channels. how to signal a transfer and what methods are best for transferring either large amounts of data or small packets that may only consist of single byte. PSoC® 5 Architecture Technical Reference Manual (TRM). The main points of this section is to consider how to construct a component to use DMA. Document # 001-42697 Rev. TD/ CFGMEM and the downstream spokes. SYSMEM. The PHUB essentially utilizes a multi-layer AHB architecture allowing for simultaneous AMBA-lite style mastering. methods of data transfer utilizing DMA. it is a separate bus master. The diagram below illustrates the general connectivity between the CPU. To reduce the complexity PSoC Creator Component Author Guide. CPU PHUB CPU INTERFACE CHn CSRs CHn CSRs CHn CSRs CH ARB DMAREQ[N:0] SPK0 (AHB) TD/ CFGMEM LOCMEM ARB DMAC SYSMEM LOCAL SPOKE / PHUB CSR SPOKE ARBITRATION SPOKES to Peripherals The details with regard to the register map are contained in the PSoC® 3. The points of concern here are that the DMA controller offloads the CPU.

The data registers contain the constant data for a given function. or CRC polynomial. F1 11. There are two 4-byte FIFOs to provide a source and destination for buffered data. for example.2 Registers for Status There are four FIFO status signals. Document # 001-42697 Rev. the count. The FIFOs can be configured both as input buffers. The “bus” status is primarily intended for the system bus control for CPU/DMA interaction (when the system should read or write bytes). The “bus” status is meaningful to the device system and is usually routed to the interrupt controller. interrupts. A1 Data D0. 11. These registers are non-retention. They also may be loaded from an associated data register or FIFO. which is determined by static configuration. Examples of usage include buffered TX and RX data in SPI or UART and buffered PWM compare and buffered timer period data. both as output buffers. These FIFOs generate status that can be routed to interact with sequencers. CRC. continuous data streams can be maintained without the loss of data. the accumulator should be used especially when a single packet of data will be transmitted or received and where computation on the data is necessary before another packet is sent. thesystem bus writes to the FIFO. Along with the FIFO status logic. Accumulator A0. and the system bus reads from the FIFO. such as a state machine built from PLD macrocells. There are two status bits generated from each FIFO block that are available to be driven into the UDB routing through the datapath output multiplexer. Each datapath module has six 8-bit working registers.3. FIFOs are particularly useful. The meaning of the status depends on the configured direction (Fx_INSEL[1:0]) and the FIFO level bits. For an input buffer. They retain their value across sleep intervals. is tied to the reading and writing of these registers. or shift. they lose their value in sleep and are reset to 0x00 on wakeup. FIFOs are non-retention.3. For an output buffer. FIFO status logic is reset on wakeup. or one input and one output buffer. Type Name Description The accumulators may be a source for the ALU and destination of the ALU output. The meaning of these signals depends on the direction of the given FIFO. 96 PSoC Creator Component Author Guide. or DMA requests. and datapath internals read the FIFO. which can be individually configured for direction as an input buffer or an output buffer. The “block” status is primarily intended for local control to provide FIFO state to the internal UDB state machines. timer period. DMA controller. These registers are retention.Best Practices of configuration a DMA wizard is provided for the end user. such as a PWM compare value. datapath internals write to the FIFO. Each datapath contains two 4-byte FIFOs. D1 FIFOs F0. fifo1_bus_stat and fifo1_blk_stat.1 Registers for Data Transfer System bus connections are common to all UDBs and allow DMA access to registers and RAM in the UDBs for both normal operation and configuration. The accumulators contain the current value of the function. fifo0_blk_stat. or it could be polled through a status register. For small transfers. They lose their contents in sleep and the contents are unknown on wakeup. The “blk” status is meaningful to the internal UDB operation and is normally routed to the UDB component blocks. which can be routed as a datapath output. All registers are CPU and DMA readable and writable. For large data transfers that require continuous streams of data. As part of the component development the capabilities of the component with regard to DMA may be provided in an XML file. *G . Status signaling. two for each FIFO: fifo0_bus_stat.

the Datapath may idle. When full. I2C. The following table defines the peripherals associated with a spoke and the width of the spoke. This status is asserted when there is at least 1 byte available to be read from the FIFO. PWMs DFB UDBs group 1 UDBs group 2 Spoke Datawidth 32 16 32 16 16 32 16 16 The source spoke and destination spoke can be different sizes. Flash programming interface Analog interface. When empty the control logic may idle or generate underrun status. This status is asserted when there is room for at least 2 bytes in the FIFO. the Datapath function may write bytes to the FIFO. The address can take on any value for 8-bit transfers. SWV. The burst engine will use the FIFO within the DMA controller as a funneling mechanism between the two spokes. *G 97 . This means that if the overall burst starts or ends on an address boundary that doesn’t equal the datawidth of the spoke. This status can be used to assert a system interrupt or DMA request to read these bytes out of the FIFO. PSoC Creator Component Author Guide. AHB rules require all data transfers be aligned to the address boundary equal to the size of the transfer. Timers. This status can be used to assert a system interrupt or DMA request to write more bytes into the FIFO.3.Best Practices FIFO level bits (Fx_LVL) are set in the auxiliary control register in working register space. EMIF PHUB local configuration. and ADR[0] of 16-bit transfers must equal 0. Counters. Interrupt controller. Fx_INSEL Fx_LVL Signal [1:0] Input 0 Status Description This status is asserted when there is room for at least 1 byte in the FIFO. Power manager. This status is asserted when there are no bytes left in the FIFO. Clocks. Options are shown in the following table.3 Spoke width The DMA controller transfers data on a spoke in sizes equal to the datawidth of the spoke. PHUB Spokes 0 1 2 3 4 5 6 7 Peripherals SRAM IOs. When not full. the Datapath function may consume bytes. fx_blk_stat Full This status is asserted when the FIFO is full. Decimator USB. Which means ADR[1:0] of 32-bit transfers must equal 0b00. then this creates a ragged start or end. CAN. EEPROM. When not empty. However. or generate overrun status. 11. fx_bus_stat Not Full Input Input 1 N/A fx_bus_stat At Least Half Empty fx_blk_stat Empty Output 0 fx_bus_stat Not Empty Output Output 1 N/A fx_bus_stat At least Half This status is asserted when there is at least 2 bytes Full available to be read from the FIFO. PICU. Document # 001-42697 Rev.

Note In the dynamic FIFO control mode.3. including constants. d0_load and d1_load are not available for their normal use in loading the D0/D1 registers from F0/F1. ALU outputs. starting with external access (dx_load == 1). *G .Best Practices 11. In a given usage scenario. Document # 001-42697 Rev.5 Datapath Condition/Data Generation Conditions are generated from the registered accumulator values. and FIFO status. The datapath input signals d0_load and d1_load are used for this control. the datapath can perform operations on the data. 11.3. The 16 possible conditions are shown in the following table: Name ce0 cl0 z0 ff0 ce1 cl1 z1 ff1 ov_msb co_msb cmsb so f0_blk_stat f1_blk_stat f0_bus_stat f1_bus_stat Condition Compare Equal Compare Less Than Zero Detect Ones Detect Compare Equal Compare Less Than Zero Detect Ones Detect Overflow Carry Out CRC MSB Shift Out FIFO0 block status FIFO1 block status FIFO0 bus status FIFO1 bus status Chain? Y Y Y Y Y Y Y Y N Y Y Y N N N N Description A0 == D0 A0 < D0 A0 == 00h A0 = FFh A1 or A0 == D1 or A0 (dynamic selection) A1 or A0 < D1 or A0 (dynamic selection) A1 == 00h A1 == FFh Carry(msb) ^ Carry(msb-1) Carry out of MSB defined bit MSB of CRC/PRS function Selection of shift output Definition depends on FIFO configuration Definition depends on FIFO configuration Definition depends on FIFO configuration Definition depends on FIFO configuration 98 PSoC Creator Component Author Guide. Then toggling back to external access. or to globals and I/O pins. These conditions can be driven to the UDB channel routing for use in other UDB blocks. the dynamic control (dx_load) can be controlled with PLD logic or any other routed signal. Then toggling to internal access (dx_load == 0).4 FIFO Dynamic Control Description The configuration between internal and external access is dynamically switchable via datapath routing signals. the CPU or DMA can read the result of the computation. for use as interrupts or DMA requests. For example. the CPU or DMA can write one or more bytes of data to the FIFO.

3. All configurations are writable as 16 bits to support DMA or as 16-bit processor operations. 16-bit Working Registers – A bus master with 16-bit capability can access 16-bits per bus cycle to facilitate the data transfer of functions that are inherently 16-bits or greater. Document # 001-42697 Rev.Best Practices 11. These are the registers that CPU firmware and DMA interacts with during the normal operation of the block. Once configured. with two registers responding to the access. are normally left in a static state during function operation. There are three unique address spaces in the UDB pair. the same 8-bit UDB hardware registers are accessed. 11. and the DP configuration RAM. The PLD has unique read signals which implement RAM read and write timing.   PSoC Creator Component Author Guide.3. These registers maintain their state through sleep.  8-bit Working Registers – A bus master that can only access 8-bits of data per bus cycle can use this address space to read or write any UDB working register. 8 or 16-bit Configuration Registers – These registers configure the UDB to perform a function. *G 99 . Although this address space is mapped into a different area than the 8-bit mode. There are three types of interfaces: the PLD.6 UDB Local Bus Configuration Interface The following figure illustrates the structure of the interface of the configuration state to the UDB local bus interface. They are also separately writable as upper (odd addresses) and lower (even addresses) bytes. the configuration latches. The CFG registers and DP CFG RAM share the same read and write control signals.7 UDB Pair Addressing Methods of data transfer using DMA depend on how the working and configuration registers are configured.

where the register number is in the upper nibble and the UDB number is in the lower nibble. the working registers for 16 UDBs can be accessed with an 8-bit address. *G . The following figure shows the registe-r map for one UDB. On the left.or 16-bit objects and each of these access methods has a different address space. mask register. UDB 2 A0 A1 UDB 1 A0 A1 UDB 0 A0 A1 Low byte Low byte 16-bit UDB Array data bus Low byte Only one byte at a time can be accessed in this mode and the PHUB will naturally align the valid odd (upper) or even (lower) byte back to the processor or DMA. On the right is the 16-bit address. the 8-bit address scheme is shown. FIFOs. With this scheme. Document # 001-42697 Rev. 8-bit addresses UDB Working Base + 0xh 1xh 2xh 3xh 4xh 5xh 6xh 7xh 8xh 9xh Axh Bxh 16-bit addresses 0xh 2xh 4xh 6xh 8xh Axh Cxh Exh 10xh 12xh 14xh 16xh A0 A1 D0 D1 F0 F1 ST CTL/CNT MSK/PER ACTL MC Note that UDBs can be accessed as 8. which is always even aligned. and the auxiliary control register.7. all UDB registers are accessed on byte-aligned addresses.7. status and control registers. The upper 4 bits is still the register number. 11.2 8-Bit Working Register Access In 8-bit register access mode. Working registers are organized into banks of 16 UDBs.Best Practices 11. The UDB number is 5 bits instead of 4 due to the even address alignment. All data bytes written to the UDBs are aligned with the low byte of the 16-bit UDB bus.1 Working Register Address Space Working registers are accessed during the normal operation of the block and include accumulators. A total of 9 address bits are required to access 16 UDBs in 16-bit data access mode.3.3. as shown in the following figure. 100 PSoC Creator Component Author Guide. data registers.

the lower and upper bytes are written to UDB0 and UDB1.3. it is recommended that 8-bit DMA transfers in 8-bit working space be used for functions over 16 bits. the default mode accesses a given register in UDB ‘i’ in the lower byte and the same register in UDB ‘i+1’ in the upper byte.3 16-bit Working Register Address Space The 16-bit address space is designed for efficient DMA access (16-bit datawidth).4 16-bit Working Register Address Limitation There is a limitation in the use of DMA with respect to the 16-bit working register address space. respectively. It is inefficient for use when the function is greater than 16-bits. This address space is optimized for DMA and CPU access to a 16-bit UDB function. an access at A0.7. *G 101 . For example. you will overwrite the value in UDB1 with the lower byte of that transfer. the 16-bit UDB array data bus has access to pairs of registers in the UDB. returns A0 in the low byte and A1 in the high byte.Best Practices 11. PSoC Creator Component Author Guide. Document # 001-42697 Rev. In this mode. There are two modes of 16-bit register access: “default” mode and “concat” mode. To avoid having to provide redundant data organization in memory buffers to support this addressing.3. This is because the addressing is overlapped as shown in the following table: Address 0 2 4 Upper byte goes to UDB1 UDB2 UDB3 Lower byte goes to UDB0 UDB1 UDB2 When the DMA transfers 16 bits to address 0. On the next 16-bit DMA transfer at address 2. where the registers of a single UDB are concatenated to form 16-bit registers.7. UDB i A1 D1 F1 CTL/CNT ACTL 00h 16-bits at UDB i A0 D0 F0 ST MSK/PER MC High byte Low byte 16-bit UDB Array data bus 11. This makes 16-bit data handling efficient in neighboring UDBs (address order) that are configured as a 16-bit function. UDB 2 A0 A1 UDB 1 A0 A1 UDB 0 A0 A1 Low byte 16-bits at UDB 2 High byte Low byte 16-bits at UDB 1 High byte Low byte 16-bits at UDB 0 16-bit UDB Array data bus The following figure shows the concat mode. As shown in the following figure.

8 DMA Bus Utilization The DMA controller has a dual context in that they can be pipelined and thus can act in parallel. As data is being read from the SRC spoke and written into the DMA controller FIFO. the DST engine can write available FIFO data to the DST spoke. In that case there are two of these N+1 length bursts that occur.Best Practices 11. provided there is no spoke contention or contention for the source (SRC) or destination (DST) engines of the DMA controller. inter-spoke DMA Intra-spoke DMA requires the entire SRC burst to first be buffered in the DMA controller FIFO before the data is then written back out to the same spoke. The arbitrating. fetching. *G . Thus an ideal burst on a spoke involves N+1 clock cycles to transfer N pieces of data. inter-spoke DMA is more efficient. the spoke buses can achieve virtually 100% utilization for AHB bus cycles attributed to moving data. the data bursts of one channel can overlap with the data bursts of another channel. Document # 001-42697 Rev. The following table shows the cycle times for some example ideal bursts: Data Transactions (Spoke-Sized) 1 2 3 N Intra-Spoke DMA Burst Phase (Clock Cycles) 4 6 8 2N+2 Inter-Spoke DMA Burst Phase (Clock Cycles) 4 5 6 N+3 102 PSoC Creator Component Author Guide. The initial control cycle on each spoke plus one “redundant” data cycle (it takes one data cycle on each spoke to move each piece of data).3. An ideal burst involves an initial control cycle followed by a burst of data cycles (with subsequent control cycles pipelined in parallel). Inter-spoke DMA allows the SRC and DST bursts to overlap.3. The overhead of processing a channel is generally hidden in the background of data bursting. The burst conditions of the channel:        Competition against the CPU for use of the spoke SRC/DST peripheral readiness SRC/DST peripheral widths Length of the burst Ragged starts and ends Intra-spoke vs. 11. where N = burst length / peripheral width. Thus the general formula for an ideal inter-spoke DMA burst is N+3 to move N pieces of data. and thus the general formula for an ideal intra-spoke burst is 2N+2. or updating for a channel can occur in the background of the data bursting of another channel. Additionally. There are multiple variables that can affect this number:  Existence of another channel context ahead in the DMA controller context pipe and the burst conditions that remain for that channel. The net result is that there are three overhead cycles to move a single piece of data from one spoke to the other.9 DMA Channel Burst Time Channel burst time is defined as the number of clocks it takes from the first request on the SRC spoke to the final ready on the DST spoke. As a result of this overlapping. Generally.

Best Practices

11.3.10

Component DMA capabilities
Any component that wants to provide its ability to work with the PSoC Creator DMA Wizard needs to have an XML file that includes its DMA capabilities. The XML format must include the ability to reflect instance specific information. This should be done with a static XML file that can have settings that are based on parameters set for the instance.

11.4

Low Power Support
As a general rule, components provide support for low power by providing APIs to retain nonretention registers and user parameters that would be lost during the exit from a low power mode. An API to save registers and parameters is called prior to entering a low power mode. Then an API is called after exiting the low power mode to restore registers and parameters. The specific registers to save are a function of the registers used in a design. The TRM specifies which registers are nonretention. Only the non-retention registers need to be saved when entering a low power mode.

11.4.1

Functional requirements
Provide a static data structure, based on the component, to maintain the non-retention register values. The low power mode functions are implemented only when necessary. This gives consistent interfaces for all components. Templates are defined for both the data structure and the functions required to initialize, save/restore, and sleep/wakeup. All of these functions are global. The save/ restore functions may be used outside of the low power context.

11.4.2

Design Considerations
Define low power retention functions when necessary. These functions are placed in a separate file, `$INSTANCE_NAME`_PM.c. This allows the .o file with the static data structure to be removed at link time if the application does not use the low power functionality. In addition, the `$INSTANCE_NAME`_Enable() and `$INSTANCE_NAME`_Stop() functions enable/disable the alternate active register enables. This provides a mechanism to automatically enable and disable the alternate active template.

11.4.3
11.4.3.1

Firmware / Application Programming Interface Requirements
Data Structure Template
typedef struct _`$INSTANCE_NAME`_BACKUP_STRUCT { /* Save component’s block enable state */ uint8 enableState; /* Save component’s non-retention registers */ } `$INSTANCE_NAME`_BACKUP_STRUCT;

11.4.3.2

Save/Restore Methods
Save non-retention register values to the static data structure. Save only the specific component register values. `$INSTANCE_NAME`_SaveConfig() { /* Save non-retention register’s values to backup data structure. */ }

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

103

Best Practices

Restore non-retention register values from the static data structure. Restore only the specific component register values. `$INSTANCE_NAME`_RestoreConfig() { /* Restore non-retention register values from backup data structure. */ } Save the enable state of the component. Use this state to determine whether to start the component on wake-up. Stop the component and save the configuration. `$INSTANCE_NAME`_Sleep() { /* Save component’s enable state – enabled/disabled. */ if(/* Component’s block is enabled */) { backup.enableState = 1u; } else /* Component’s block is disabled */ { backup.enableState = 0u; } `$INSTANCE_NAME`_Stop(); `$INSTANCE_NAME`_SaveConfig(); } Restore the component configuration and determine if the component should be enabled. `$INSTANCE_NAME`_Wakeup() { `$INSTANCE_NAME`_RestoreConfig(); /* Restore component’s block enable state */ if(0u != backup.enableState) { /* Component’s block was enabled */ `$INSTANCE_NAME`_Enable(); } /* Do nothing if component’s block was disabled */ }

11.4.3.3

Additions to Enable and Stop Functions
Enable the component's alternate active register enable. `$INSTANCE_NAME`_Enable() { /* Enable block during Alternate Active */ } Disable the component's alternate active register enable. `$INSTANCE_NAME`_Stop() { /* Disable block during Alternate Active */ }

104

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

Best Practices

11.5
11.5.1

Component Encapsulation
Hierarchical Design
When reusing a design in a hierarchical design system, you can take advantage of the following features:
Designs can incorporate other designs. A building block approach means that you do not need to know or spend time on the internal details of the design – just the interface to that design. The interface can be hardware, software, or both.

Single or multiple instances of a design are easy to add and organize at multiple levels.

Parameterization allows designs to be reused, but have different behavior or characteristics for different applications.

To make it easy to reuse a design with PSoC Creator, it should be encapsulated as a PSoC Creator component. A design can be considered for encapsulation and reuse if it meets one or more of the following criteria:
 

Implements a specific function. The general rule is that it should “do just one thing and do it well.” Has a limited and relatively small set of inputs and outputs, in the form of either hardware terminals or API calls. The general rule is the fewer the better, but not so few that essential functionality is reduced.

The following pages provide a few examples:

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

105

they really are not part of the essential design functionality. it has a limited and small set of inputs and outputs. Plus. *G . consider what you might do if you are required to have a window comparator in your design. the VDACs could have been brought into the component. So the basic. However.Best Practices In one of the simpler examples of when to encapsulate IP as a component. Document # 001-42697 Rev. The reference voltages could be provided by VDACs or by some other source. With PSoC Creator you would most likely design it as follows: This design is a good candidate for encapsulation as a component. essential functionality of the design can be encapsulated into a component. It implements just one specific function: a window comparator. 106 PSoC Creator Component Author Guide. It would also have a small API to start the comparators. A window comparator activates when an input voltage is between two compare voltages. with a symbol. as follows: When encapsulating a design. In the above example. So in this case it is better practice to leave the VDACs out. an important decision is what to leave out of the component. which is simply comparing a voltage to two reference voltages.

Best Practices With encapsulation your top-level design becomes simpler: And in many cases it is easier to scale the design: PSoC Creator Component Author Guide. Document # 001-42697 Rev. *G 107 .

The original design uses two SIO pins with different thresholds. and not necessarily their sources. the basic design requires only the digital signals CH_hi and CH_lo.Best Practices The following the mag card reader example is more complex. 108 PSoC Creator Component Author Guide. Again. Also. In this design. you need to look at what to leave out of the component. *G . because it is a well-defined and limited function it is a good candidate for encapsulation: Again. Document # 001-42697 Rev. These could have been brought into the component but it is better practice to keep pins at the top-level design. there is a central ADC and reference section along with multiple copies of circuitry for reading a single channel: The basic design functionality in this case is converting the analog inputs from the channel into a form that is readable by a digital system.

DMA channels. Finally. If it is encapsulated then the relevant issues and limitations should be communicated such that the user becomes aware of the issues as soon as an attempt is made to reuse the component. flash. along with possible voltage. an alert output on a fan controller may be set to be active high or active low.5.Best Practices Also. too much usage of less obvious resources such as analog or DSI routing.5. for example: CPU or bus_clk speed. and multiple instances may not fit in some smaller PSoC 3/5 devices.  Incorporates critical resources in the PSoC 3/5. but perhaps not known when the component is reused. SRAM or CPU cycles   Operates only under certain conditions. USB. a single fan controller component might have a parameter for number of fans to be controlled. components can be parameterized. the user can then connect the pins to the component symbol at a higher level. the design makes use of limited analog resources and routing. like SPI and I2C. thereby conserving clock resources. since PSoC 3/5 opamps are closely associated with specific device pins. opamps. If a design meets one or more of the criteria listed below.3 11. so different versions of the component can be kept together. CAN.3. comparators. timers. Fan controllers with two different interfaces. or only with certain parts such as the PSoC 5 family. This fact. *G 109 . 11. Terminals should be used instead. or speed limitations should be communicated to the user. the behavior of an instance of a component can be set at build time (typically by using a dialog box). That is. For example. thereby making those resources unavailable in the higher-level design. Multiple instances of the IP cannot be implemented. it may not be good practice to encapsulate it. what frequency should PeakClk be? It is known at the top level of the original design. DACs. The advantage of not embedding a clock is that multiple components can be connected to the same clock.1 Component Design Considerations Resources Components should avoid embedding pin components. etc. Document # 001-42697 Rev. or Vdd levels. might be two separate components in the “Fan Control” library project.  If parameterization causes large changes to the functionality of different instances. and I2C too much usage of more abundant resources such as UDBs. clocks. then you should consider encapsulating the design in multiple components. temperature. The differences in behavior are not expected to change at run-time. This brings up an interesting issue: when NOT to encapsulate a design. A component can include a parameterization option to make a clock internal or external. it may actually be better to keep the opamp out of the component.5. Parameterization should be used in cases where:  Different instances of the IP behave slightly differently but the overall functionality is unchanged.  11. For example. Specific topics include:   usage of single-instance fixed-function blocks such as ADC_DelSig. interrupts. For example.2 Parameterization In PSoC Creator. Clock components may or may not be encapsulated in a component. pins. Both hardware and software behavior can be set up by parameterization. PSoC Creator Component Author Guide. PSoC Creator allows multiple components to be packaged in a single library project.

whereas a firmware-only component could have just a .c. . and wakeup.2 Power Management Components should be designed to support power management issues. .h. Verilog (. Reference Component Symbol The symbol should always have an instance name `=$INSTANCE_NAME` (backward single quotes) annotation included. Components developed under this specification should have as a minimum a symbol file and a datasheet file. and documentation (. a hardware-only component could have just a schematic or Verilog file. Other annotations should be added such that the user may more rapidly understand the function of the component.cysym).v). hibernate.). in which case the interrupt and DMA should not be embedded in the component.pdf.3. A component may generate a “have data” signal that could be connected to either an IRQ or a DRQ. . 11. Components can contain several different file types: symbol (. Cypress-provided components offer many examples of how to implement a power management API. They cannot be built nor can they be installed in a target device.5. etc. Components can also reference other components.Best Practices Interrupts and DMA channels may or may not be encapsulated in a component.h and . 11.c file for an API. Document # 001-42697 Rev. All other file types are optional depending on the function of the component. thus enabling hierarchical design techniques. such as sleep. schematic (. They are intended to be linked into standard PSoC Creator projects which are then built and installed.a51. *G .3 Component Development PSoC Creator components are basically just containers. 110 PSoC Creator Component Author Guide.txt). APIs should include appropriate functions.3.5. firmware source code (. For example.cysch).

lower case. For example. For information about versioning. the test projects should support both PSoC 3 and PSoC 5. especially if you create multiple components. Component Versioning The component name can include version information. see Component Versioning on page 14. PSoC Creator Component Author Guide. Document # 001-42697 Rev. Components should be versioned. 11. alpha character. a datasheet should be included.4 Testing Components Reusable designs are encapsulated as components in a PSoC Creator library project. see Define Catalog Placement on page 29. debug and release. The datasheet should include the design considerations mentioned above. programmed or tested. A consistent tab and tree node naming scheme should be developed. For more information.3.Best Practices Component Catalog Placement The symbol property Doc. Note that using fewer tabs and more tree nodes will create a better fit in the Component Catalog on most users’ screens. Note that in order to do this either multiple instances of the component may need to be used or multiple test / demo projects may need to be created. As much as possible.5. see Add/Create Datasheet on page 81. standard and bootloadable. The reference component should be included with each of its parameters set to as many different settings as possible. in various configurations. All macros should be used at least once. So one or more standard projects should be developed along with the component. which is done by appending the following to the component name: “_v<major_num>_<minor_num>_<patch_level>” Both <major_num> and <minor_num> are integers that specify the major and minor version numbers respectively. and different compiler optimization settings. <patch_level> is a single. Library projects cannot be built. For information about how to add a datasheet.CatalogPlacement controls where the user may find your component in the PSoC Creator Component Catalog. different PSoC 5 compilers. However neither a library project nor a component by itself is very useful. All functions in the component’s API should be called at least once. Component datasheet To properly document your component. for the purpose of testing or demonstrating the functionality of the reusable design in that component. *G 111 .

*G .6 Verilog Many digital components use Verilog to define the implementation of the component. This Verilog must be written in the synthesizable subset of Verilog. In addition to conforming to the Verilog subset. This synthesizable subset is similar to the subset implemented in other Verilog synthesis tools. Implement sequential logic using non-blocking assignments This rule causes the simulation results of clocked logic to match the hardware implementation. 11. but they are never inferred by the synthesis process. The remaining UDB resources can be instantiated into a Verilog design. the results can differ.6.1 Synthesizable Coding Guidelines Blocking versus Non-Blocking Assignments The Verilog language has two forms of assignment statements. PSoC Creator will automatically run the Warp synthesis tool included as part of the PSoC Creator installation. The non-blocking assignment statement assigns the value later when time progresses.2. The specific synthesizable subset of Verilog supported by PSoC Creator is specified in the Warp Verilog Reference Guide. When these assignments are considered from a synthesis perspective and the resulting hardware. For more information.2 11. always @(posedge clk) begin state <= nextState. The blocking assignment statement assigns the value immediately before progressing to the next statement. Additional guidelines are specific recommendations related to the development of a PSoC Creator component. The synthesizable portion of the Verilog design will be synthesized into PLD logic. Many of these guidelines are practices accepted as best practices for any synthesis tool. The best practices for a synthesizable design were developed so that the simulation results and the synthesis results match.6. Document # 001-42697 Rev.Best Practices 11. end nextstate clk state 112 PSoC Creator Component Author Guide. In the hardware implementation all registers clock in new state before that state is used to compute the next state.1 Warp: PSoC Creator Synthesis Tool When processing any digital logic in a design.6. there are additional guidelines that should be followed when creating a Verilog-based component. Refer to the guide for a detailed description of the Verilog constructs supported. see Implement with Verilog on page 36. These two types of assignments have a specific meaning from a simulation perspective. 11. This is a PSoC-specific version of the Warp synthesis tool that has been used in the past with Cypress programmable logic devices.

In this case results of one level of logic are used to compute the next level of logic immediately. This combinatorial logic can be implemented in a separate combinatorial block or in a continuous assignment statement. The following rules should be followed when coding with these statements. PSoC Creator Component Author Guide. then the default statement is already present.Best Practices Implement combinatorial logic in an “always” block with blocking assignments This rule causes the simulation results to assign values to signals immediately as the always block is evaluated. Y = X & C. Including a default condition where the combinatorial result is assigned prevents the synthesis of latches in the design. This rule is particularly important within a combinatorial always block. With the casez statement this isn’t a concern since PSoC designs will not have “z” values internal to the synthesizable portion of the design. Do not make assignments to the same variable in more than one always block The synthesis engine in PSoC Creator will enforce this rule and generate an error if this rule is violated. casex. If a case-item is removed or the width of the case is changed.6. always @(A or B or C) begin X = A & B. That will automatically satisfy this rule. but with the casez statement only the “z” value will match don’t care bits in case-items. Document # 001-42697 Rev.2. 11. Fully define all case statements This is best implemented by placing a default case into all case statements. This matches the hardware implementation when the delay through combinatorial logic is ignored. The casex statement will match input values of “x” or “z” when a case-item specifies a don’t care bit. *G 113 .2 Case Statements In Verilog there are three forms of a case statement: case. Including a default statement even when all cases are already covered will cause this rule to continue to be satisfied when case-items are changed later in the development of the code. end A B X C Y Do not mix blocking and non-blocking assignments in the same always block This rule implies that combinatorial logic that requires more than a single assignment to implement should be described in a block separate from a sequential always block. Use casez instead of casex The casex and casez statements are similar and synthesize to the same result. With the casex statement. and casez. simulations can miss uninitialized value design errors. The difference is in the results generated during simulation.

This parameter statement will automatically be created in the Verilog template that can be created automatically from the symbol.3 Parameter Handling Using parameters allows a Verilog instance to be synthesized based on the specific requirement of a component instance. This method is appropriate for settings that can be made at build time. The initial value will always be overridden with the value set for the specific instance of the component. Passing parameters to a component The parameters for a component configured on the symbol can optionally be passed to the Verilog instance by setting “Hardware” in the Misc settings for the parameter to True. but it can be difficult to determine the intended logic. Do not use casez statements with overlapping conditions A casez statement with overlapping case-items will result in the synthesis of a priority encoder. Determining which parameters should be static and which need to be dynamic (run time changeable) will influence the complexity and resource requirements of the component.Best Practices Use the “?” for don’t care bits in casez statements This rule has no impact on the synthesizable code. The alternate method where a “z” is used does not indicate the intent. but can’t be used for settings that will need to be determined at run time. It is just for clarity to indicate that the intention is that that the specified “?” bits are don’t care. *G . A Verilog based component that has a Hardware parameter will get access to that parameter value with a parameter statement. When a parameter is passed to a Verilog module the parameter setting will be applied before synthesis is performed.6. The use of if-else if-else statements more clearly conveys the priority encoder intent. parameter Interrupt = 0. Settings that can be changed at run time will need to be controlled by software through the datapath or control registers. 11.2. Document # 001-42697 Rev. The result is that the specific instance will be synthesized based on the parameter settings. 114 PSoC Creator Component Author Guide. The resulting logic is identical to the simulation results.

. // Remainder of the value not shown here }.cy_dpconfig_a(config0)) dp0 ( // Remainder of the instance not shown here ). This functionality can be implemented using a Verilog generate statement. it is often the case that the same configuration value will be used for multiple configuration parameters. In the other method. from the Verilog-2001 specification. The only method to implement that functionality is a generate statement. *G 115 . Document # 001-42697 Rev.interrupt(interrupt) ).cy_md_select(7’h07). so a parameter value can be used so that the configuration data is only present in one place.cy_force_order(1). Parameterized datapath instances Datapath instances are configured based on a single complex configuration parameter. The original method is the defparam statement. The parameter names and values are included after a “#” in the module instance. Duplicating the same information is prone to error and difficult to maintain. cy_psoc3_statusi #(. parameter [7:0] Resolution = WIDTH_8_BIT. For example if a component can have either an 8-bit or 16-bit implementation. There are two ways that parameters can be passed in Verilog.Best Practices Generate statements Often the value of a parameter will result in the need for significantly different Verilog code based on that value. parameter config0 = { `CS_ALU_OP_PASS.clock(clock). cy_psoc3_dp8 #(.status(status). generate if (Resolution == 8) begin : dp8 // Code for 8-bit end else begin : dp16 // Code for 16-bit end endgenerate Passing parameters to module instances A Verilog design will need to pass parameters to other modules that are instantiated in the design. .cy_int_mask(7’h07)) stsreg( . PSoC Creator Component Author Guide. . . Parameters are required by many of the standard hardware modules. that will result in the need to instantiate either an 8-bit or 16-bit datapath component. parameters can be passed using named parameters. It is recommended that parameters always be passed using named parameters. For multibyte datapath configurations or for components that use generate statements to support multiple possible datapath widths.

In many cases this input is driven by a macrocell output. By using an asynchronous reset. If the clock is a free running clock. The rules and description use the term reset. this long path can often be split into two shorter paths. the timing from the reset signal propagated through the logic becomes the limitation on timing.6. and finally is used as the control store address.4 Latches Latches should be avoided in a PSoC design. Document # 001-42697 Rev.6. that a latch was not the intended functionality. then the synchronous more of reset will have the same result without the added timing issues of an asynchronous signal.2. 11. To increase performance. If a register needs to be reset while the clock is not running. condition generation.6. PLD logic). *G . the latch will be implemented using cross coupled logic. then the only additional timing analysis is simply the relationship of the reset signal with respect to the clock. When a synchronous reset is used.3 11. A selection is made to use this signal as a reset. The natural place to insert a register in this path is often times before the control store address input. That is not the case for PSoC devices. The option of having both an asynchronous reset and set is not available in the hardware. then an asynchronous reset signal will be required. Use synchronous reset if possible An asynchronous reset acts like a combinatorial path from the control signal to the output of all registers that it impacts. It is often the case that when a latch is present in a design. Alternatively this can be avoided by assigning a default value for each output at the top of the always block. The time taken by that combinatorial path is determined by the mapping of the Verilog design to the available hardware.2. Some programmable logic devices have latches built into their architecture. Registering the control store address The longest path in a design that uses a datapath is often the path starting at a datapath accumulator or macrocell flip-flop that then goes through combinatorial logic (ALU. but this applies to both reset and set functionality.3. a set or not use the signal. The use of latches limits the capability to do timing analysis due to the loop construct that is created. 11.5 Reset and Set The following rules should be followed for reset and set signals. Each macrocell can be combinatorial or registered on a clock edge. This can be avoided by assigning to each output in every if-else clause and including a final else clause in an if-else chain. Asynchronous reset and set can not be used for the same register The hardware implementation for the PLD macrocells uses a single signal for asynchronous reset and set. The combinatorial latch based implementation can also have timing issues since the length of the feedback paths is not controlled. 116 PSoC Creator Component Author Guide.1 Optimization Designing for Performance The performance of a typical digital component is determined by the longest combinatorial path between two registers. If a latch is created in a PSoC design. Use synchronous reset when the clock is free running The only case where an asynchronous reset should be required is when the clock is not free running.6. A latch will be inferred during synthesis for any output from a combinatorial always block where there is at least one path through the block where the output is not assigned a value.Best Practices 11.

it can be beneficial to register the outputs of the component. If the outputs from the component are used to feed another component. When building logic for the PLD. this logic is packed into PLDs. the specific architecture of the PSoC PLD must be taken into consideration. Split PLD paths Each PLD has 12 inputs and 8 product terms. so this type of implementation should be part of the initial architecture definition of the component. the number of inputs required for any one output is limited to 12. then registering these outputs will result in more predictable timing relationship between the output signals. Working with the 12 input PLD architecture The PSoC PLD has 4 outputs and 12 inputs. Pipelining in this way does change the operation of the component.3. This will add a PLD propagation delay and routing delay for every additional level of PLD path required. 11. Document # 001-42697 Rev. Ideally each PLD will be used to produce 4 outputs. These registers can be used without any resource usage impact to pipeline a design. If the final output requires more than 12 inputs. If an output requires more inputs or product terms than can be implemented in a single PLD. case statements and in the assignment statement for a particular output need to be counted. the output portion of that path will be minimized. PSoC Creator Component Author Guide. Registering outputs Depending on the typical usage model for a component. then the function is broken into multiple logic pieces where each requires 12 inputs or less.Best Practices Since all macrocell outputs have an optional register. then the only other outputs that can also be placed in that PLD will need to only require those same inputs.2 Designing for Size Typically the size of the programmable digital portion of a design is either limited by the PLD resources or by the datapath resources. When the design is synthesized. This will only be possible if the equations for 4 outputs can be found that when combined only need 12 inputs. To improve performance any of these levels could be calculated in a pipelined fashion. making this output registered does not increase the resources used for the component. then the that implementation is likely the most resource efficient implementation method. each of the conditions generated by the datapath is available as a combinatorial signal or as a registered value. The equivalent logic functionality of the datapath resources is much larger than the logic available in the PLD array. If a datapath implementation is possible. the equation for the output will be split into multiple PLDs. If there is more than one output and they are sent to pins. Pipelining will however change the timing relationship for the logic. Registering the conditional outputs Much like every macrocell in the PLD has an available flip-flop that can be optionally used. If the outputs are registered. If for example a single output requires all 12 inputs. This can be done without increasing resources since registers are available for every macrocell output. then the performance of the system will be dependent on the output timing from this component and the input timing of the destination component. After all the logic has been split into outputs requiring 12 or less inputs.6. To determine the number of inputs that are needed to calculate a specific output all the inputs that are used in if statements. *G 117 .

y(cmpOut)). All digital components will use PLD logic. To improve the packing. use the cy_buf component. In some cases this can be done by restructuring the equations to consolidate a group of inputs to a single input.x(cmp). For example. If this value is used to calculate multiple outputs (a multi-bit register). wire cmp = (count == 10’h3FB). To force a signal to be the output of a macrocell.0 and the number of inputs is approaching 12. *G . The output of a cy_buf will always be a macrocell output.Best Practices The first step is to build the component and observe the average statistics for the packed PLDs from the report file. All synthesized logic will be placed in PLDs.4 Resource choice A Verilog component implementation can use various resources that are available in the PSoC UDB architecture. then the number of inputs required is the limiting factor in your design. cy_buf cmpBuf (. if a multi-bit comparison is an input. If the average number of macrocells is significantly below 4. 118 PSoC Creator Component Author Guide. Some components will also use datapath instances. then forcing a specific partition of the logic can result in significant size reduction.0. the number of inputs required will need to be reduced. 11.6. . Which resource to choose depends on the functionality required. Datapath implementation must be done by including a datapath instance in the Verilog design. then that can be replaced by a single result input. Document # 001-42697 Rev.

12 input bits per PLD limits the efficiency and performance of wide functions. but for some complex multi-cycle calculations (shift. To get data from the CPU a control register is used. so that limits the output to being A0 or A1. decrement or stepping by a constant. Maximum number of register bits equal to the number of UDBs * 8 (depends on the selected device). There are 8 dynamic operations available. then they can write the value to a FIFO or register in the datapath. Parallel to serial and serial to parallel conversions where the parallel connection is on the CPU side and the serial connection is on the hardware side. There are up to 6 register sources (A0. This restricts the ability to use the datapath where other hardware needs to provide a parallel value.   Limitations of the datapath  Parallel input into the datapath is limited. Typical datapath applications  Any operation where a FIFO is required. If multiple operations are required. but the parallel output value is always the left input to the datapath ALU. The two datapath FIFOs are the only FIFO path in the programmable digital system. General purpose combinatorial logic  Limitations of the PLD  The PLD does not have a direct path from or to the CPU. inc) this can be a limitation.Best Practices 11. Most counting functions including increment.     11. D0. Typical PLD applications   State machines Small counters (<= 4 bits) or counters where parallel input and output to other hardware are required. If enough cycles are available. Only 2 registers are read/writable by the datapath. then a value can be serially shifted in. add. Alternatives to parallel hardware loading may be possible.   PSoC Creator Component Author Guide. *G 119 . and it restricts the ALU operation that can be performed while using parallel output to also use that value as the left input of the ALU function. Parallel output is possible. The control and status registers can be used to augment this number of bits.4. A1).1 Datapath The datapath resource has many times the equivalent logic gate capability as the PLD resource. This is typically enough operations. To send data to the CPU a status register is used. F1). For some designs the datapath can be used just to add the FIFO functionality to a PLD based hardware design. but only 2 registers that can be written and then read back (A0. Document # 001-42697 Rev. For example a wide mux function does not map well into the PLD.6.4.2 PLD Logic The PLD logic resource is the most flexible digital hardware resource. so if applicable to the application the datapath resource should be the first choice.6. Registers are available to count. preload. D1. then a multi-cycle implementation using an multiple of the effective clock may be possible. but neither of those resources provides a register that can be both written and read by the PLD. If the CPU or DMA can get access to the value. A1. compare and capture. The left input to the ALU can only be A0 or A1. Only one ALU function can be performed at a time. F0.

Best Practices 120 PSoC Creator Component Author Guide. *G . Document # 001-42697 Rev.

and the document properties of the referenced SYMBOL. An instance context consists of the formal and local parameters of the instance. but adds a different type system. including their precedence. A document context consists of the formal and local parameters from the document. and an instance context. which is better suited to PSoC Creator application requirements. Most annotations are evaluated in the document context. A. The evaluation of local and formal parameters was discussed in Formal versus Local Parameters on page 22.2.1 Evaluation Contexts There are two basic evaluation contexts: a document context. or by end users. as well as the the document properties.2. A. PSoC Creator Component Author Guide.2 Error Values of the error type may be created automatically by the system. A. The expression evaluation language is similar to the Perl 5 language. Expression Evaluator The PSoC Creator expression evaluator is used to evaluate expressions in PSoC Creator (except those in the debugger). Annotations associated with instances are evaluated in the instance context. *G 121 . expressions in strings. It borrows most of its operators. Document # 001-42697 Rev. This provides a standard means by which evaluation expressions can generate custom errors.1 Bool Legal values include true and false. This includes parameter values. double precision 8-bit signed integer 8-bit unsigned integer 16-bit signed integer 16-bit unsigned integer 32-bit signed integer 32-bit unsigned integer Character string A.A. Annotations can have embedded expressions.2 Data Types The expression evaluator includes the following first class types:           bool error float int8 uint8 int16 uint16 int32 uint32 string Boolean (true/false) The error type Floating point. and code generation templates.

147.4 Integers Sized.483. Type INT8 UINT8 INT16 UINT16 INT32 UINT32 Valid Values -128 to 127 0 to 255 -32. Currently.Expression Evaluator A. \\ and \” are the only supported escape sequences in strings.2. enclosed in double quotes (“). 1.483. Document # 001-42697 Rev.648 to 2. Written as [+-] [0-9] [. The following table shows the valid values for each specific type. Stored as . 1..647 0 to 4294967295 A. only ASCII characters are recognized by the parser. 1.NET strings internally (UTF-16 encoded Unicode). 122 PSoC Creator Component Author Guide.3 Float 64-bit double precision IEEE floating point.2. Integers may be expressed in any of the following three bases:    hexadecimal – starts with 0x octal – starts with 0 decimal – all other sequences of digits Unsigned integer literals are written with a “u” suffix.2. e5 A.767 0 to 65535 -2. signed. and unsigned integers.5 String Sequences of characters. -1e10.[0-9]*]? [eE [+-]? [0-9]+] Legal: 1.768 to 32.147.2.0.1e-10 Illegal: . *G .

then false.3 Data Type Conversion Due to the Perl 5 inspired nature of the language. The one exception to the conversion rule is the error type. but the error type may not be converted to any other type.2 Error Dest Type Bool Float Int String Rules Illegal Illegal Illegal Illegal A.3 Float Dest Type Bool Error Int String Rules If the value of the float it 0. *G 123 .0. True becomes 1.1 Bool Dest Type Error Float Int String Rules Becomes a generic error message. True becomes 1. A.3. A. then false. All data types may be converted to the error type.3. Becomes a generic error message. The precise format of the string is determined automatically. True becomes “true”.3. False becomes “false”. true.0.4 Int Dest Type Bool Error Float String Rules If the value of the int is 0. Document # 001-42697 Rev. Becomes the nearest floating point equivalent value. true. If the resulting value does not fit in a 32 bit integer. False becomes 0. False becomes 0. Becomes a generic error message.0. Converts the string to its decimal integer representation PSoC Creator Component Author Guide.3. Otherwise.Expression Evaluator A. then the conversion yields 0. Converts the float to a string representation. Generally this means appending a “. The rules for data type conversion are very clear and predicable.0”. Otherwise. A. all data types are capable of being converted to every other type (with a single exception). Decimal portion is dropped and the resulting integer portion used.

Expression Evaluator

A.3.5

String
Strings are a special case. There are 4 sub-types of strings. These include:
 

bool-ish strings have the value “true” or “false”. float-ish strings have a floating point value as their first non whitespace characters. Trailing characters that are not a part of the float are ignored. int-ish strings have an integer value as their first non-whitespace characters. Trailing characters that are not a part of the float are ignored. other

A.3.5.1

Bool-ish string
Dest Type Bool Error Float Int Rules If “true” then true, if “false” then false. Becomes an error message with the text of the string. If “true”, then 1.0. If “false” then 0.0 If “true”, then 1. If “false” then 0.

A.3.5.2

Float-ish strings
Dest Type Bool Error Float Int Rules Non-float looking text is dropped and the float part converts exactly like a real float. Becomes an error message with the text of the string. Non-float looking text is dropped and the float text is converted to a real float. Non-float looking text is dropped and the float part converts exactly like a real float.

A.3.5.3

Int-ish strings
Dest Type Bool Error Float Int Rules Non-float looking text is dropped and the float part converts exactly like a real int. Becomes an error message with the text of the string. Non-float looking text is dropped and the float text is converted to a real int. Non-float looking text is dropped and the float part converts exactly like a real int.

A.3.5.4

Other strings
Dest Type Bool Error Float Int Rules If the value is the empty string or “0”, then false. All other strings convert to true. Becomes an error message with the text of the string. Becomes 0.0. Becomes 0.

124

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

Expression Evaluator

A.4

Operators
The expression evaluator supports the follow operators (in order of precedence from high to low).
        

casts ! unary+ unary*/% +-. < > <= >= lt gt le ge == != eq ne && || ?:

All operators force their arguments to a well defined type and yield a result in a well defined type.

A.4.1

Arithmetic Operators (+, -, *, /, %, unary +, unary -)
Arithmetic operators force their arguments to a number using the following rules in order:
  

If either operand is an error, the result of the operation is the left-most error. If either operand is a float or is a float-ish string, then both values are forced to proper floats. Otherwise both operands are forced to integers.

If both operands are integers and at least one is unsigned then the operation is performed as an unsigned operation. Arithmetic operators always yield an error value or a number of the same type as the operands after the operands have been converted using the rules defined above.

A.4.2

Numeric Compare Operators (==, !=, <, >, <=, >=)
Numeric comparison operators force their arguments to a number using the exact same rules as the arithmetic operators. Numeric compare operators always yield a bool value. If both operands are integers and at least one is unsigned then the operation is performed as an unsigned operation.

A.4.3

String Compare Operators (eq, ne, lt, gt, le, ge)
String compare operators force their arguments to strings, unless either operand is an error. If either operand is an error, the left-most error is the result of the operation. String compare operators always yield an error value or a string.

A.4.4

String Concatenation Operator ( . )
The string concatenation operator acts like the string compare operators for the purposes of converting argument values. Note If the concatenation operator is directly preceded or followed by a digit, then it will be interpreted as a float (e.g., 1. = float; 1 . = string concatenation).

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

125

Expression Evaluator

A.4.5

Ternary Operator ( ?: )
 

If the first operand, the bool value, is an error type then the result is an error type. If the bool value is true, the value and type of the result is that of the expression between the ? and the :. If the bool value is false, then the value and type of the result is that of the expression that follows the :.

A.4.6

Casts
Casts (lowercase: cast) are of the form: cast(type, expr) Casts evaluate the expression and convert the result of expr to the named type.

A.5

String interpolation
The expression evaluator is capable of interpolating evaluated expressions embedded in strings. The format is: `= expr` The `= marks the beginning of the expression. The = sign is not interpreted as part of the expression. Since the next ` found ends the expression it is not possible to nest `= blocks inside other `= blocks. Multiple expressions, provided they aren’t nested, may be embedded in the same string and they will all be evaluated and interpolated. There is only one evaluation pass over the embedded expression. If the resutling string is a legal expression it will not be evaluated as an additional step. The portion of the string from the starting ` to the ending ` is replaced with the result of the expression between the ` and `.

A.6

User-Defined Data Types (Enumerations)
From the perspective of the expression system user-defined types are simply integers. User-defined type values can appear in expressions but they are converted to the integer equivalent before being evaluated in the expression. See Add User-Defined Types on page 27 for information about how to add user-defined types to your symbol.

126

PSoC Creator Component Author Guide, Document # 001-42697 Rev. *G

PSoC Creator Component Author Guide.B. and perform whole datapath copy. Document # 001-42697 Rev. no datapath is active and all datapath options are disabled. localparam. The tool works only with existing Verilog files. Some operations are applicable only for the datapath (such as deleting a datapath or editing the initial register values). After opening a Verilog file. paste.1 General Functionality Use the Datapath Configuration Tool to:     read an existing Verilog file modify existing datapath configurations create new configurations delete existing configurations You can then save changes back into the same Verilog file without affecting any of the other Verilog implementations. create or delete operations. copy and paste data between configurations or within a single configuration. refer to Implement with Verilog on page 36. This appendix provides instructions and information that will help you modify your Verilog files using the tool. You can edit any bit field. *G 127 . These could be defined as a parameter. If the configuration is defined as a parameter. B. edit comments. For information about implementing a component using Verilog. or directly in the datapath as a named parameter. The active datapath is the datapath to which the selected configuration belongs. The tool displays all found configurations in the Configuration list drop down at the top of the application. Datapath Configuration Tool The Datapath Configuration Tool is used to edit datapath instance configurations in a Verilog implementation of a PSoC component. it cannot be used to create a new Verilog implementation. it is parsed for existing datapath configurations.

When a bit-field is defined with a parameter that parameter name is displayed as the value and is displayed with the blue background color. CFG10. a register binary value field. The current selection is called the “active configuration” or “selected configuration. Unused bits – Unused bit fields are read-only and are always initialized with a 0 value. Document # 001-42697 Rev.2. The Binary value field is read-only. Disabled bit fields – Bits that are not used in the active configuration. CFG9. Bit fields controls are typically drop down list with predefined values. Bit field parameters – Each bit field can be replaced by a parameter value instead of one of the constant value.” Configuration registers Data Grids – Contains the Reset register button to restore the whole register to its default configuration.Datapath Configuration Tool B. These bit fields are indicated as disabled with a gray background and no value in the field. User can enable them using the context menu of these bits.2 B. They are always initialized with a 0 value.     128 PSoC Creator Component Author Guide. *G . Bits may be disabled with a particular revision of silicon. CFG11 registers are mask registers and their value can be toggled by clicking on the individual bit buttons.1 Framework Interface The main form has the following elements:  Configuration drop down list – Contains all configurations found in the active Verilog file. bit field configuration controls and comment field.

3 B.2. Opens the About dialog. Document # 001-42697 Rev.2 Edit Menu Menu Item Copy Datapath Paste Datapath Paste Dynamic Reset Datapath New Datapath Delete Datapath Shortcut Description [Ctrl] + [c] Copies the selected datapath configuration Pastes full datapath configuration from the Clipboard into the active [Ctrl] + [v] datapath Pastes the full dynamic configuration information of the datapath configuration from the Clipboard into the active configuration (all 8 registers of the dynamic configuration are pasted) Resets the current datapath configuration to the default bit field values Add a new datapath instance Delete a datapath instance B.2.2.1 General tasks Launching the Datapath Configuration Tool To launch the tool. *G 129 .2.2.2.4 Help Menu Menu Item Documentation About Shortcut Description [F1] Open this documentation. To begin working with the tool you must open an existing Verilog file. it will not contains any datapath configuration information.v Verilog files) Closes the active file Provides access to previously opened files [Ctrl] + [s] Saves the active document Displays a dialog to save the active file to another file Exit the PSoC Datapath Configuration Tool B. When the application launches.3 View Menu Menu Item Shortcut Description Initial Register Values Displays a dialog to configure initial register values for the active datapath B. which provides build information B. go to the Start menu and select Cypress > PSoC Creator 1.2.3. PSoC Creator Component Author Guide.0 > Component Development Kit > Datapath Configuration Tool.2.Datapath Configuration Tool B.2 B.2.1 Menus File Menu Menu Item Open Close Recent Files Save Save As Exit Shortcut Description [Ctrl] + [o] Displays a dialog to open an existing file (Filtered for .

2 Opening a Verilog File 1. The dialog closes and the tool gathers all appropriate information from the Verilog file and updates the rest of the window. To open open a Verilog file. Navigate to and select the file to update. and then click Open. select Save As from the File menu.3 Saving a File To save the active file. select Save from the File menu.Datapath Configuration Tool B.3. Note: You can also open recent files without this dialog using Recent Files on the File menu or dragging a Verilog file directly onto the main form of the application. To save a file with another name and/or in a different location. The Open Verilog Dialog displays. 2. Document # 001-42697 Rev. 130 PSoC Creator Component Author Guide. select Open… from the File menu. *G . B.3.

2 Adding Parameter to Mask Bit Fields To add a parameter to a mask bit field.4. Adding Parameter to Enumerated Bit Fields Enumerated bit fields contain an Add Parameter context menu item. *G 131 . right click on the bit field and select Edit Parameter from the context menu. separate bits become read-only.1 Working with Bit Field Parameters In addition to a fixed set of predefined constant fields. select Add Parameter from the context menu in the Value column. select Remove Parameter from the context menu in the Value column. After adding a parameter.Datapath Configuration Tool B. the drop down menu of the bit field will include all the predefined constants. After adding a parameter. and type the name of parameter. To remove a parameter. B.4 B. as well as any added parameter value as selection choices. Document # 001-42697 Rev. bit fields support a parameter value. To change a parameter name. it will be displayed with blue color indicating that it is not one of the predefined values. When the parameter value is selected.4. This command allows you to provide any parameter name as an additional choice for the bit field. PSoC Creator Component Author Guide.

4. other bit fields may become unused. That parameter is then used by datapath instances. All configurations are added to the Configuration drop down list. Both methodologies can be used within the same Verilog file. 24. The reason is that CMASK0 EN bit is set to DSBL and MSB SI bit is set to REG. Both methodologies are supported by PSoC Datapath Configuration Tool. “_c” or “_d” depending on which byte of the instance the configuration is for. This methodology is used by the Counter library component.1 Configuration naming For the datapath instance case the label is the datapath instance name. On the screenshot above bits CMASK0. Depending on their value. 16. This methodology is convenient when the same configuration is used by multiple instances to eliminate duplication and simplify maintenance of the component. SI SELB. The second methodology assigns the configuration for a datapath to a parameter. some bit fields became disabled depending on the value of other fields. B. B. dp24 and dp32 datapath instances the configuration labels are suffixed with “_a”. For the parameter instances case the label is the parameter name.5 Working with Configurations There are two methodologies that can be used to configure the elements of a datapath instance. a separate set of values is used for each byte of the overall instance. For the dp8.5. 32) is added at the end of the configuration name in the drop down.3 Bit Field Dependencies Datapath configuration has a few bits which have an influence on other bits. “_b”. The first methodology directly places the configuration of the datapath in the datapath instance.Datapath Configuration Tool B. Also the datapath size (8. and SI SELA are disabled. For multi-byte datapath instances. dp16. 132 PSoC Creator Component Author Guide. This is a common methodology used when a particular configuration is only used once in a Verilog file. *G . Document # 001-42697 Rev. To make it visual for user.

To paste a separate register. select Paste Register from the context menu of any bit field that belongs to that register. is 0.5.3 Copy. Paste Configuration To copy the active configuration data to the Clipboard. select Paste Dynamic from the Edit menu. B. The data is not saved to the verilog file until the main menu operation “Save” or “Save As” is completed. select New Datapath from the Edit menu.4 Resetting Configuration To reset the current datapath configuration to the default bit field values. Bit fields of each register can be changed by choosing one of the predefined values in the cell drop down list or adding a parameter. This command will replace all bit fields and comments of the active configuration with values from the Clipboard. The default comment value for dynamic registers is Idle and for all other registers is an empty string. To paste the configuration data from the Clipboard.Datapath Configuration Tool B.5. to copy it initially you should use the Copy command as well. B.2 Editing Configuration To make the configuration active. All changes made to the active configuration are stored automatically to object storage in the application. The dialog New Datapath will appear. PSoC Creator Component Author Guide. B.1 Working with Datapath Instances Creating a New Datapath Instance To create a new datapath. press the button of the Reset column of data grid in that row on the main form. Document # 001-42697 Rev. To paste only the dynamic registers data. To copy a separate register. Note: If you want to paste only the dynamic registers data. select it in the Configuration drop down list. select Copy from the Edit menu. *G 133 . use Reset Datapath on the Edit menu. To reset a particular register of the datapath configuration to its default values. so the user can switch between different configurations without losing data.6. select Copy Register from the context menu of any bit field that belongs to that register.5. select Paste from the Edit menu. For the mask bit fields of CFG9-11 the default is 1. The default value for all of the bit fields.6 B. except the mask fields of CFG9-11.

Datapath Configuration Tool Type the name of the new datapath in the Instance Name text box.3 Setting Initial Register Values To set the initial register values for the active datapath.6. B. or dp32). this option is disabled in the menu. A new datapath will be inserted at the end of the current verilog file before the endmodule. use Initial Register Values on the View menu. Then press OK to submit changes. Initial values are passed to a datapath as named parameters. If the datapath has multiple configurations (dp16. all of them will be deleted. If there are no active datapaths. Check the boxes near the entries that will be defined and enter either an 8-bit hexadecimal value (8’h?) or a parameter value in the edit field. and press OK. *G . B. New datapath configurations would be initialized with all of the default bit-field values.6. dp24. all input signals would be connected to 1’b0 and all output signals would be unconnected. 134 PSoC Creator Component Author Guide.2 Deleting the Datapath Instance To delete the active datapath select Delete Datapath from the Edit menu. select datapath type. Document # 001-42697 Rev. so any values not defined will not be passed to the datapath and will be set internally to their default values. this option is disabled in the menu. If there are no active datapaths. The dialog Initial Register Values will appear.

Sign up to vote on this title
UsefulNot useful