edk_tut

Xilinx EDK Tutorials and Notes12

by

Jonathon W. Donaldson

Sandia National Laboratories

1Website: https://rm-rfroot.net/files/edk tut/edk tut.pdf2This document was typeset with LATEX 2ε . LATEX 2ε is an extension of LATEX. LATEXis a collection of macros for TEX.

Contents

List of Tables 3

List of Figures 4

List of Acronyms 6

1 Introduction 7

2 Creating an EDK Project from Scratch 8

3 Simulating Your EDK Design 23

4 Adding Custom IP To Your EDK Design 274.1 Manually Changing the Number of S/W Accessible User-Registers . . . . . . . . . . . . . . 274.2 Creating your own MUI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2

List of Tables

3

List of Figures

2.1 Creating a New XPS Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 Adding the Required IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3 Bus Interface List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.4 JTAG and System Bus Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.5 DCM Port Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6 Reset Controller Port Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.7 PPC 405 Port Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.8 PLB and OPB Port Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.9 System Address Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.10 Add Software Application Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4

List of Acronyms

BRAM Block Random Access Memory, 11, 18, 19BSB Base System Builder, 22

DCM Digital Clock Manager, 10, 12–15, 23DCR Device Control Register, 11, 15DDR Double Data Rate, 11DPLB Data Processor Local Bus, 11

EDK Embedded Development Kit, 7–11, 15, 17–20,23–25, 28

FPGA Field Programmable Gate Array, 7, 8, 10, 12, 13,15, 19–21

FPGAs Field Programmable Gate Arrays, 7, 8

GUI Graphical User Interface, 9, 15

IBM International Business Machines, 10IF Interface, 11, 18IP Intellectual Property, 8–11, 28IPLB Instruction Processor Local Bus, 11ISE Integrated Software Environment, 23

JTAG Joint Test Action Group, 7, 10, 11, 19, 20

MGT Multi-Gigabit Transceiver, 23MHS Microprocessor Hardware Specification, 8, 9, 13,

15, 23, 25MPD Microprocessor Peripheral Description, 28MSS Microprocessor Software Specification, 9

OCM On-Chip Memory, 21

5

OPB On-Chip Peripheral Bus, 10, 11, 13, 15, 20OS Operating System, 20

PAO Peripheral Analyze Order, 24, 25, 28PLB Processor Local Bus, 10, 11, 13, 15, 18PPC PowerPC, 7–11, 13, 14, 17–19PPC440 Power PC 440, 10PPC405 Power PC 405, 8–10, 13, 14, 18PPM Parts Per Million, 23

SDK Software Development Kit, 18

UART Universal Asynchronous Receiver-Transmitter, 7,11, 15, 17–20, 26

UCF User Constraints File, 15USB Universal Serial Bus, 7

XMP Xilinx Microprocessor Project, 8XPS Xilinx Platform Studio, 7, 18XST Xilinx Synthesis Tool, 15XUPV2P Xilinx University Program Virtex-II Pro Develop-

ment Board, 7, 8, 13, 20

6

CHAPTER 1

Introduction

This document will teach you a bit about the Xilinx Platform Studio (XPS) and Embedded DevelopmentKit (EDK) tools and how to get a project up and running from scratch without using the Base SystemBuilder wizard. This tutorial is based on the Xilinx University Program Virtex-II Pro Development Board(XUPV2P) which can be purchased at http://www.digilentinc.com. The board only costs $300 for students,but is $1600 for commercial use. If you don’t have this board available don’t worry. The actual boarddoesn’t matter just so long as you have a board with a Xilinx Field Programmable Gate Array (FPGA) anda Universal Asynchronous Receiver-Transmitter (UART) port.

In my experience working with development boards from various vendors, the XUPV2P is quite possi-bly the best one I have ever had the privilege of using. In my opinion, it is the most versatile and accessiblelearning tool you could ask for when beginning to work with Field Programmable Gate Arrays (FPGAs).Additionally, you don’t need to buy one of the $125+ dollar Xilinx Joint Test Action Group (JTAG) Program-ming cables because they provide the Universal Serial Bus (USB) JTAG programming cable chip embeddeddirectly onboard. You can simply plug in a standard USB device cable from your PC to the board.

The only other development board I’ve worked with that outranks the XUPV2P is the Xilinx ML310,which is essentially a 100% customizable dual-core PowerPC (PPC) processor motherboard. Unfortunately,the board is prohibitively expensive, therefore it lacks the ”accessibility” aspect of the XUPV2P. Fortunately,however, I own two of them, so if you happen to be lucky enough to own an ML310 be sure to lookfor another tutorial on that board in the coming months. And I neglected to mention that the ML310 hasalso been discontinued by Xilinx. But no worries, they have replaced it with an even better (albeit moreexpensive) board named the ML410. The ML410 is essentially the exact same board as the ML310 exceptthat it has a Virtex-4 FX in place of the ML310’s Virtex-II Pro.

This tutorial was created using EDK 8.2i, but I have successfully followed the same steps (with veryminor differences) using Xilinx EDK 9.2i. It is necessary to learn how to create an EDK project fromscratch since Xilinx removed Virtex-II Pro (and some Spartan) support from the BSB wizard in version 9.2i.Therefore, if you are planning on using any Virtex-II pro board at all you will be without any wizard help.The process of creating an EDK project from scratch is extremely tedious (you will get an appreciation forXilinx’s BSB wizard very quickly), but I promise by the end of this tutorial you will have learned a lotmore about the inner workings of EDK and hopefully put EDK to some more advanced use.

If you have any comments/questions/requests regarding this tutorial feel free to contact me at webmaster[a t] rm-rfroot [d o t] net.

7

CHAPTER 2

Creating an EDK Project from Scratch

The project we create in this chapter will ultimately be configured to display “Hello World!” over theboard’s standard RS-232 serial port using a very simple C application. Yes, the resulting output of theproject is trivial, but I promise you will learn a lot if you’re new to EDK. If at anytime you would like toview my source code for the design you can get them from the following links. I have also created a basicEDK project layout for the Xilinx ML325 board as well (i.e. not for the XUPV2P).

• rm-rfroot.net/files/edk tut/from scratch 8 2i.zip

• rm-rfroot.net/files/edk tut/from scratch 9 2i.zip

• rm-rfroot.net/files/edk tut/from scratch ml325.zip

1. When EDK opens select ”Blank XPS Project”. No wizard for us! ;-) Click OK.

2. Pick a location for your Xilinx Microprocessor Project (XMP) (be sure the path does NOT containspaces!) in the new dialog that opens.

3. Choose the correct ”Target device” options for the FPGA you’re using.

4. Leave the Microprocessor Hardware Specification (MHS) file and Repository paths blank. Some Xil-inx boards (e.g. XUPV2P/ML310/ML410) will come with there own additional Intellectual Property(IP) core libraries. These libraries contain IP cores that are not available in the Xilinx “standard”library that comes with the EDK installation. For example, the XUPV2P board comes with an AC97codec, a PS/2 driver, etc. for special hardware specific to that board. We are not going to use themhere because we won’t need them to get a simple design up and running. Click OK. See image 2.1below.

5. You will then be presented with the default EDK interface. Your initial setup might come up with anextra EDK ”design flow” window and/or a block diagram window but you can just close them. Let’sfollow EDK’s instructions presented in the console log window and start adding some useful IPs toour design.

6. Expand the “Processor” list under the “IP Catalog” tab in the left panel, right click on the “ppc405”and select “Add IP”.1 This is shown in image 2.2. Since the xc2vp30-ff896 FPGA contains two Power

1If you’re using a Virtex-5 then the processor selection will be “ppc440”.

8

Figure 2.1: Creating a New XPS Project

PC 405 (PPC405) processors, EDK will require that we add IP cores2 for both of them even if we donot intend on using both in our design. EDK won’t complain if you don’t add a second IP for theother PPC405 just yet, but it will be sure to error out if you don’t add it before you try to implementthe design. So just repeat this step now and save yourself the trouble.

7. Our fancy new processor isn’t going to be much use unless we connect it to some components so let’sdo that now. Add the following IP cores in the same fashion as you did for the PPC405:

• proc sys reset - This is a reset control block which is very useful (and necessary). It has aport for an external reset input which, when toggled, will perform resets to the internal PPCcomponents, the processor bus structures, and the peripherals in a very specific order. It alsohas internal reset ports which connect to the processor itself. The PPC has its own set of “resetrequest” signals which can tell the reset control block to reset the system as well.3 Also note thatthe method of adding this IP is one of the difference for EDK versions prior to 9.2i. If you areusing EDK 9.2i or later this core will not be readily available in the IP Catalog list. But neverfear, the IP can still be added manually using the MHS file.4 To do this, double-click on “MHS

2Note that the PPC IP we are adding here is not the actual netlist data for the PPC core. The PPC cores in Xilinx FPGAs are“hard” cores and are immersed directly in the FPGA fabric. The IP we are adding are merely “wrappers” that allow us to interfacewith the processor.

3For more information on the reset control block right-click on it in the IP Catalog list and select “View PDF Datasheet”. SeeXilinx document DS406 for more information on the reset block. See the “Reset Interface” section of Xilinx document UG018 formore information on the PPC reset signals.

4In fact, when you add IP using the Graphical User Interface (GUI) method the only thing EDK is doing is updating the MHSand/or the Microprocessor Software Specification (MSS) files.

9

Figure 2.2: Adding the Required IP

File” under the “Project” tab in the left panel and add the following lines.

BEGIN proc_sys_resetPARAMETER INSTANCE = reset_blockPARAMETER HW_VER = 1.00.aEND

• jtagppc cntlr - This block is a wrapper that activates the FPGA’s built-in JTAGPPC primitive.It allows us to interface to the PPC for debugging (e.g. single-stepping the process, etc) via thechip’s JTAG port. Even if you do not plan on debugging your design (yeah, right) EDK requiresthat you add this IP. Note that you can connect up to two PPC primitives to this controller blockso we only need one.

• dcm module - regardless of whether or not you have the exact oscillator frequency you planon using in your design you will still need a Digital Clock Manager (DCM) module for tworeasons: (a) the proc sys reset module requires a DCM Locked output signal for its logic and(b) it’s good design practice to buffer your external input clock and running your external clockthrough a DCM automatically does this for you and makes your design more versatile if differentclock rates are required in the future.

• plb v34 - The Processor Local Bus (PLB) is part of the International Business Machines (IBM)CoreConnect Bus Architecture specification and is the high-speed data interface to the PPC core.All of our peripherals and system memory will communicate with the processor using this bus.If you are using a Virtex-5 device you may want to consider adding two PLB cores - one for datafetching and one for instruction fetching. Having two PLB interfaces only really makes sense inthe Virtex-5 devices because the Power PC 440 (PPC440) is capable of out-of-order executionand has a longer 5-stage pipeline than the PPC405.5

5If you are using a Virtex-4/5 the IP Catalog will reference the newer PLB v4.6 instead of v3.4.

10

• opb v20 - The On-Chip Peripheral Bus (OPB) is another piece of the IBM CoreConnect BusArchitecture specification, but has been deprecated for use by Xilinx.6 However, I want to use itin this tutorial because in my next tutorial I will teach you how to add a custom IP core to yourdesign, and the OPB has a very simplistic interface and is a good learning segway when juststarting to learn about the IBM CoreConect Bus Architecture.

• plb2opb bridge - The PLB2OPB bridge will allow low-speed peripherals to interact with theprocessor over the PLB (remember, the PLB is the only physical interface to the PPCfor ourperipherals). This bridge will act as a “slave” on the PLB and a “master” on the OPB.

• bram block - We will use Block Random Access Memory (BRAM) as the processor’s mainmemory in this design just to keep things simple. However, in a larger design with larger appli-cations you will most likely want to use Double Data Rate (DDR) memory (if your board has aDDR slot available). Xilinx provides DDR controller cores as well.

• plb bram if cntrl - This module will be our interface to the BRAM. If you are using BRAM asmain system memory or cache space you will need one of these controllers.

• opb uartlite - This is an RS-232 UART core that we will use to transfer characters to a standardVT100 terminal (e.g. HyperTerminal, TeraTerm Pro, etc.). Compared to the Xilinx 16550 com-pliant UART the UARTlite is very simplistic and only has a few configurable registers/parameters- when Xilinx says “lite” they mean it!7

Please see image 2.3 to see what the ”Bus Interface” list should now look like. I changed someof my core instance names but you don’t have to. Just make sure you don’t try to name them thesame as the actual IP name or EDK will thrown the following warning: “WARNING:MDT - Couldnot rename instance: New instance name for (plb bram if cntlr 0) must be different from IP name(plb bram if cntlr)”.8

That’s it! We’ve got all the cores we need (at least for this little demonstration anyway). Now we justhave to connect them together so they can communicate properly.

8. First, connect the JTAG PPC Controller to both of the PPC cores. Note that we are still only goingto use one PPC core, but EDK will throw an error if we don’t connect the JTAG controller to the onethat is not being used. Nothing else will have to be connected to the second PPC core. Do this byconnecting the respective JTAG controller ports under the bus connection column to each processor.See image 2.4.

9. Now let’s connect up our main system buses. In this design both data and instructions will pass overthe same Processor Local Bus (PLB) bus (i.e. we won’t have one for instruction and one for data).So select the PLB instance name under the Bus Connection column for the Data Processor Local Bus(DPLB) and Instruction Processor Local Bus (IPLB) bus interface’s for ppc405 0.9 See image 2.4.

10. Now, connect the PLB2OPB bridge as a slave on the PLB and a master on the On-Chip PeripheralBus (OPB). See image 2.4.

6The OPB bus was deprecated because Xilinx has corrected many of the arbitration issues that existed between high- and low-speed devices that were fighting for access to the processor. Now that those issues are fixed, most devices can share the same PLBwithout much concern.

7Xilinx actually gives you all of the VHDL source code for this little core. If you’re interested just look in the EDK installdirectory.

8This warning doesn’t actually have anything to do directly with EDK at all, VHDL syntax does not allow you to have instancenames identical to that of the module (unlike Verilog).

9We will not be using the Device Control Register (DCR) bus at all in this design.

11

Figure 2.3: Bus Interface List

11. Now attach the RS232 UARTlite as a slave on the OPB. See image 2.4.

12. Connect the PLB Block Random Access Memory (BRAM) Interface (IF) Controller as a slave on thePLB. And also connect the BRAM block itself up to the BRAM IF controller on PORTA (we will onlyhave one memory block in this design so we won’t use PORTB of the BRAM IF controller at all).While you’re at it, also right-click on the PLB BRAM IF controller, select “Configure IP. . . ”, selectthe “System” tab, select “PLB” from the configuration list, and change PLB clock period to matchthe period of whatever speed clock you connected it to (in my case it was 10000ps or 100MHz). Seeimage 2.4.

13. Check image 2.4 below and make sure your design has the same bus interfaces as mine.

14. Now let’s get down to the nitty gritty parts. Change the tab near the top of the window from ”BusInterface” to ”Ports”. There are a ton of signals to connect here so let’s get started. First, let’s get someclock connections in place. Expand the Digital Clock Manager (DCM) instance block and attach theRST input to “net gnd”.10. Now, for the “CLKIN” port select “Make External” for the connection -this will be the input from the onboard oscillator. For the CLK0 output choose “New Connection”from the drop down list. For the DCM’s clock feedback input (CLKFB) select the signal name that isbeing used for the CLK0 output.11 Finally, make a new connection for the LOCKED output as well.The DCM port list should look like image 2.5.

While we are here, right-click on the DCM instance and choose “Configure IP...”. In the “DCM”section, change the “Configuration Startup Wait” option to “True”. This will cause the design to beheld in reset until the DCM has locked (as I mentioned earlier). Additionally, change the “Input ClockPeriod” parameter to match your input clock period (in nanoseconds) - for my board this was “10.0”.

10This may seem strange but it’s a perfectly valid configuration because we are going to configure our entire system to wait forall DCM’s to lock before releasing the FPGA’s Global Set/Reset signal - I will show you how to do this later

11We want the CLK0 output of the DCM to feed right back into itself to allow the DCM to correctly adjust for clock skew (thisis recommended by Xilinx).

12

Figure 2.4: JTAG and System Bus Connections

!WARNING!: Make sure that the value you enter here has at least one decimal place because theDCM wrapper requires a floating point data type for this parameter, and if the number does not containat least one decimal place the synthesis tool will error out when it tries to synthesize the DCM.

In the ”Buffers” section, change the BUFG option for the CLK0 output to True. Do not place aBUFG on the CLKIN or CLKFB inputs to the DCM because it needlessly uses up a BUFGP andwill result in poor routing inside the FPGA. We do, however, need to insert an IBUFG between theexternal oscillator port and the DCM CLKIN input, but we can’t do that here. Click OK, and open upthe MHS file under the “Project” tab in the left panel. Near the very top of the file locate your DCM’sCLKIN port and add/change the parameter “SIGIS” to “SIGIS=DCMCLK”. Doing so will preventthe mapping tool from wasting the BUFGP.

15. Next, let’s connect up the system reset block to the PPC. For the “Slowest sync clk” port just choosethe slowest clock frequency that will actually be used by any device in the entire system. Forthis design, that frequency will be the CLK0 output of the DCM. For “Ext Reset In” port select

13

Figure 2.5: DCM Port Connections

“Make External” - later on we will connect this signal to one of FPGA’s reset inputs that is con-trolled by a “Triple Supply Monitor” (LTC1326CS8) chip (component U23 on the XUPV2Pboardschematic).12 The LTC1326CS8 asserts its reset outputs to the FPGA when one of the input sup-ply voltages drops below a certain threshhold or when an optional push button input is asserted.Now connect the “Dcm locked” input port to the “dcm 0 locked” output signal of the DCM mod-ule that we created earlier. Then, select “New Connection” for the ”Rstc405resetcore/chip/sys” portsfrom the drop-down list which will be used to connect to the PPC405 later. The 3 inputs named”Core/Chip/System Reset Req” will be driven by the PPC core itself when it needs to reset due tosome fatal error condition.13 Finally, create a new connection for the ”Bus Struct Reset” output - thiswill be attached to the PLB and OPB later. Normally, we would also use the ”Peripheral Reset” outputport, but our only peripheral (the OPB UARTlite) was originally designed to connect to the OPB busdirectly so its reset port is connected to the OPB’s reset signal by default. Finally, and ONLY if yourexternal reset input is active low (like it is on the XUPV2P), right-click on the reset control block andchange the “External Reset Active High” input to 0 (i.e. false).

16. Under the PPC instance, create new connections for the three “C405RSTCHIP/CORE/SYSRESETREQ”ports and connect them to the reset controller’s “Core/Chip/System Reset Req” input ports as men-tioned earlier. Finally, connect the “RSTC405RESETCHIP/CORE/SYS” input ports of the PPC tothe “Rstc405resetcore/chip/sys” output ports of the reset block. Also, connect “CPMC405CLOCK”(i.e. the PPC’s main clock) to the DCM’s CLK0 output signal. In case you’re curious, the “CPM” portname prefix stands for “Clock and Power Management” and is just one of the many port groupings onthe PPC405.

17. Check to make sure that the connections for the reset control block and the PPC405 look like those in12You external reset input could be whatever you like or have available.13The connection names to these signals will not exist until we create them under the PPC405 port list.

14

images 2.6 and 2.6 below. Note that your instance and signal names could be different from mine.

Figure 2.6: Reset Controller Port Connections

18. Now, connect the PLB and OPB clock inputs to the DCM’s CLK0 output. Additionally, connect thePLB and OPB’s “SYS Rst” input port to the “Bus Struct Reset” output of the system reset controller.It should look like image 2.8. Also, right-click on the PLB instance and uncheck the box for “IncludeDCR Interface and Error Registers”. Since we won’t be using the CoreConnect’s Device ControlRegister (DCR) bus in this design, deselecting this option will reduce the amount of logic needing tobe synthesized by Xilinx Synthesis Tool (XST). While we’re at it, also right-click on the PLB2OPBbridge instance, select the “System” tab, select DCR from the list, and finally change “Include DCRSlave Interface” to 0 (i.e. false).

19. Finally, let’s finish things off with the UART ports. Select “Make External” for both the TX and RXlines of the UART. We won’t use the interrupt output for this design but in the future I would highlysuggest using the Interrupt port. For any device as slow as a UART an interrupt is really the onlyefficient way for information exchange between it and the processor. But for now just leave it andwe’ll deal with the inefficiences (which you won’t even notice in this design anyway since we onlyhave the one peripheral that needs bus access). Finally, right-click on the UART to configure it, andchange the baud rate to 115200, and change ”Use Parity” to False.

20. Phew! We’re done with the port connections! Now, open up the “system.mhs” file by changing tabs inthe left panel of the EDK window from “IP Catalog” to “Project” and double-click on “MHS File” toopen it. Inside this file you will see the fruits of your labor from attaching all of those Bus Interfacesand Ports. And, yes, you can create this file prior to even creating an EDK project, add the file toa new design, and it will update the Graphical User Interface (GUI) port and bus interface displayappropriately. In other words, instead of using the GUI to generate the MHS file we could have usedthe MHS file to generate the GUI connections. I showed you the GUI method first because it’s easierto understand what we’re trying to accomplish. In any case, we need to look at a few things in thisfile. First, locate the “opb uartlite” instance and change the C CLK FREQ parameter to whatever theOPB’s clockrate is (in my case it was “100000000”).14

14For some reason this parameter does not show up in the “Configure IP...” window for this core in EDK v8.2i. It does, however,show up in the configure panel in v9.2i (select the ”System” tab, then select ”OPB” from the left column.)

15

Figure 2.7: PPC 405 Port Connections

21. We’re not done with the MHS file just yet. Scroll to the very top and you will see the external ports thatyou defined for this design when you selected the “Make External” option. In this example you shouldonly have 4: the external clock input, the external reset input, and the TX/RX data lines for the UART.You don’t need to change anything in the MHS file but you will need to know the auto-generatedexternal port names that EDK created (i.e. the ones with the “ pin” suffix - but you can rename themtoo if you like). With the MHS file open, also open up the “system.ucf” User Constraints File (UCF)file which can also be found under the ”Project” tab in the left panel. Constrain the 4 external portsto pins on the FPGA and add the ever-important clock period constraint to your input system clock.Below are the constraints that I used.

# System Clock Input# TNM_NET = ‘‘Timing Name for Nets’’Net dcm_0_CLKIN_pin LOC=AJ15 | IOSTANDARD = LVCMOS25 | TNM_NET = dcm_0_CLKIN_pin;TIMESPEC TS_sys_clk_pin = PERIOD dcm_0_CLKIN_pin 10 ns;

# System Reset Input

16

Figure 2.8: PLB and OPB Port Connections

# TIG = ‘‘Timing IGnore’’Net tsm_pb_rst_Ext_In_pin LOC=AH5 | IOSTANDARD = LVTTL | TIG;

# PPC Core Usage ConstraintsINST ppc405_0 LOC=PPC405_X1Y0;INST ppc405_1 LOC=PPC405_X0Y0;

# Module RS232_UART constraintsNet RS232_UART_RX_pin LOC=AJ8 | IOSTANDARD = LVCMOS25;Net RS232_UART_TX_pin LOC=AE7 | IOSTANDARD = LVCMOS25 | SLEW = SLOW | DRIVE = 12;

In addition to the external port constraints notice the “PPC Core Usage Constraints”. The purpose ofthese constraints is to tell EDK that we want ppc405 0 to be associated with the right (i.e. physicallocation) PPC core rather than the left. This is the recommended by Xilinx when a design is usingonly one of the PPCs in -7 speed grade, Virtex-II Pro, dual-core devices. For more information onthese constraints you can read Xilinx document XAPP755.

22. With that complete let’s move on to defining our address space. Navigate back to the “System As-sembly View” window and change filters from “Ports” to “Addresses”. You will see a list of buses,controllers, and peripeherals. What we need to do here is section out some of the PPC’s 4GB ofaddress space for our system’s devices.

Just for fun, hit the “Generate Addresses” button at the top of the window and EDK will “automagi-

17

cally” generate the addresses it thinks is best for the design.15 My gripe with the auto-generate toolis that it way overcommits address space for every component.16 We only need a tiny bit of addressspace for our design. Change the address size of the UART 256 locations. Since we only have thisone peripheral you can also reduce the size of the PLB2OPB bridge from 64K to 256 as well.

We can also reduce the size of the PLB BRAM IF controller to give us just enough space for a tinylittle application that will print out some characters to the UART. So let’s size our BRAM to 16KB*which should be plenty of room.17

NOTE 1!: Ensure that the “High Address” of the PLB BRAM ends on 0xFFFFFFFF. This conditionmust be met, otherwise the compiler can’t place any instructions at the PPC’s reset vector and EDK

will throw an error! Please see image 2.9 below and make sure your address mapping is similar tomine (the only addresess that need to match exactly are those for the PLB BRAM IF controller).

*NOTE 2!: In EDK v9.2i Xilinx has changed the requirement for the memory mapping and systemmemory must now be on 64KB boundaries! Which means that your BRAM address range should befrom 0xFFFF0000 -¿ 0xFFFFFFFF.

Figure 2.9: System Address Mapping

23. We’re almost ready to test our design! But first, we need a small application to test the UART. To dothis, select the “Applications” tab in the left EDK panel. Double-click on “Add Software ApplicationProject...”, name your project and be sure it is set to be executed on “ppc405 0”.18 See image 2.10

15If you get a warning about the Auto-Generate Address function not supporting dual-core designs just ignore it. This problemis fixed in v9.2i.

16There is actually a good reason for doing this because creating smaller address space requires more address decode logic.17We could actually pick 8KB and it would still be almost twice the space that are little program will need, but 16KB is the

minimum memory size configuration for the Virtex-II pro using the PPC405in 64-bit data width mode. If you don’t choose at least16KB EDK will certainly let you know with an ERROR message when you try to implement the design.

18You can check the “Project is an ELF-only Project” box if any of your future applications are being maintained by the XPSSoftware Development Kit (SDK).

18

below.

Say OK to that window and then right-click on the new project name in the left panel and click “Markto Initialize BRAMs”. This tells the Xilinx EDK flow tools to embed this project compiled applicationbinary code into the FPGA’s configuration bitstream (using the ’data2mem’ program) so that it can beloaded into the BRAM along with the FPGA physical design itself.19 Now, right-click on “Sources”under the project name, select “Add New File...”, and select a location for the program’s main file.

Figure 2.10: Add Software Application Dialog

24. Double click on your new source file to open it and let’s add some code. For our UART test app wearen’t going to have much of any code at all. In fact, it’s only one function call! Create the standard‘C’ main function and then call the following function: print(‘‘Hello World!’’);. There isactually one VERY important thing to note here and that is the fact that we are calling print()and not the ‘C’ standard library printf() function. It seems like a very small difference but itis actually a HUGE difference. The print() function is a Xilinx function and it uses the bareminimum number of instructions to write characters out to the UART. The standard ‘C’ printf()function on the other hand, generates huge libraries (e.g. one library is used for printing floating pointnumbers) that won’t fit in our small BRAM - your program will very easily bloat to well over twicethe size if you mistakenly use printf() instead of print(). Now, don’t think that you can’t useprintf() if you don’t want to, be my guest, but you’ll have to more than double the size of yourBRAM (32KB should cover it if you’re interested), and you’ll also have to include the customarystdio.h library. Below is the code for the program:

int main(void) {

print("Hello World!");

19The default bootloop application already provided for you is simply an unconditional “branch-to-self” assembly instructionthat will keep the processor in a known state. You can verify this by right-clicking on it and selecting “View Source”. This littleapp needs to be used when debugging your PPC design with the JTAG debugger.

19

}

25. You may have asked yourself how does the print() (or printf() for that matter) function knowwhere to send the characters (i.e. memory address of the UART)? Well, it’s the same in EDK as itis in most other Operating System (OS)s, we have to define what are referred to as “STDIN” and“STDOUT”. To do this, click on the “Software” menu and select “Software Platform Settings...”. Inthe “OS and Libraries” section, change the “stdin” and “stdout” options to the OPB UARTlite!

While you’re in this window, let’s also go ahead and take care of one other small matter of businesswhich is located in the “Software Platform” section. Change the “CORE CLOCK FREQ HZ” pa-rameter from 400MHz to 100MHz (or whatever your system is running at). There are LOTS of othergoodies in here, including many of the controls required for successfully porting Linux to most ofthe Xilinx development boards (you can check out my Linux port study/tutorial here at https://rm-rfroot.net/xupv2p/).

26. With that out of the way let’s see if we can build our UART test application. Before we can compileand link our application we will need to create a linker script. Fortunately, Xilinx’s automatic linkerscript generator is quite good and we won’t have to do anything by hand. Right-click on your projectname again and select “Generate Linker Script...”, then click on the “Generate” button in the bottomright-hand corner of the window. The console window at the bottom of EDK should say “LinkerScript generated successfully.” Finally, right-click on your project one more time and click “BuildProject”. There shouldn’t be any errors and the console output should end with “Done!”.

27. Great! All we have to do is synthesize our hardware and we’re done! BUT, before that we shouldcreate a Xilinx iMPACT tool batch file so EDK can automatically target and program the FPGA whenit’s done generating the bitstream. This file is called “download.cmd” and it should be created andsaved in the “etc” directory where your EDK project is located. If you’re using the XUPV2P boardyou can just copy the code below. If you’re not using the XUPV2P board you should at least makesure that the “-p 3” option for the “assignfile” and “program” commands is correct for your board. The“-p” option refers to the “position” of the device you are trying to program in the board’s JTAG chain.In my case I want to program the FPGA which is third in line in the JTAG chain on the XUPV2Pboard.

setMode -bscansetCable -p autoidentifyassignfile -p 3 -file implementation/download.bitprogram -p 3quit

28. We might as well also open HyperTerminal, TeraTerm Pro, or whatever serial application you’re usingon your PC/Linux box and configure it to the same settings as the OPB UARTlite. Connect the serialcable from the board to your PC/Linux box as well. And also connect up the Xilinx programmingcable to the board and power on the board.

29. If you like, you can also edit the default “fast runtime.opt” script located in the “etc” folder of yourproject area. You can open this file from the “Project” tab in the left window pane. You can edit the

20

options to your liking. Personally, I like to add the “-timing” option to MAP and also change the MAPand PAR optimization levels from “standard” to “high”.20

30. Also, remembering that we configured the DCM module with the STARTUP WAIT=TRUE option wemust properly configure the bitgen options file so that the FPGA programming sequence is setup forthe proper order of operations.21 To do this open the etcbitgen.ut file and add the following lines:

-g GTS_cycle:1-g GWE_cycle:1-g LCK_cycle:2-g DONE_cycle:4

IMPORTANT: Make sure that there aren’t duplicates of the above options anywhere else in the file.

31. Okey-dokey! Let’s synthesize, translate, map, and place-and-route our hardware! Click on the “Hard-ware” menu at the top of the EDK window and select “Generate Bitstream”. The output from bitgenwill present you with the following strange WARNINGs:

WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin BRAMISOCMCLK for thecomp ppc405_0/ppc405_0/PPC405_i is not connected to the output of a DCMdriven clock buffer.WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin BRAMDSOCMCLK for thecomp ppc405_0/ppc405_0/PPC405_i is not connected to the output of a DCMdriven clock buffer.WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin CPMC405CLOCK for thecomp ppc405_1/ppc405_1/PPC405_i is not connected to the output of a DCMdriven clock buffer.WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin PLBCLK for the compppc405_1/ppc405_1/PPC405_i is not connected to the output of a DCM drivenclock buffer.WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin BRAMISOCMCLK for thecomp ppc405_1/ppc405_1/PPC405_i is not connected to the output of a DCMdriven clock buffer.WARNING:PhysDesignRules:1009 - Blockcheck: The clock pin BRAMDSOCMCLK for thecomp ppc405_1/ppc405_1/PPC405_i is not connected to the output of a DCMdriven clock buffer.

There is no need to worry about these warnings. First off, note that the last 4 warnings in that listrelate to “ppc405 1” which we are not using. The first 2 warnings are referring to the clock ports ofthe instruction and data side On-Chip Memory (OCM) blocks. Since we are not using any OCM forthis design you can completely disregard them.

32. Assuming the previous step was successful let’s integrate our test application’s binary into the hard-ware design’s bitstream. Do this by clicking the “Device Configuration” menu and selecting “UpdateBitstream”.

20These changes are already the default in EDK v9.2i.21If we don’t do this then the STARTUP WAIT=TRUE option will do nothing!

21

33. If the previous step went well then click the “Device Configuration” menu again and select “DownloadBitstream”. This will target the board and download your design to the FPGA. With a bit of luck youshould see “Hello World!” displayed in your serial port application’s terminal window.

34. So what have we learned from all these steps. . . ? Answer: That we should thank Xilinx for the BaseSystem Builder (BSB) wizard! ;-)

22

CHAPTER 3

Simulating Your EDK Design

First off, the following steps assume that you have already compiled the ISE and EDK libraries for Model-Sim and have updated the modelsim.ini file with the library locations as necessary.

1. First, we need to tell EDK where to locate the Integrated Software Environment (ISE) and EDKsimulation libraries. To do this click on the “Project” menu at the top and select “Project Options. . . ”.Click the “HDL and Simulation” tab, then fill in the EDK and ISE library paths. You can also changethe simulator application you are using here as well.

2. Next, we need to make a few minor modifications to our Microprocessor Hardware Specification(MHS) file. At the very top where we defined our external clock and reset inputs we need to add thefollowing parameters1:

• <external rst pin name here> = <internal rst sig name here>, SIGIS =RST, RST POLARITY = 0

• <external clk pin name here> = <internal clk pin name here>, SIGIS =DCMCLK2, CLK FREQ = 100000000

Of course, you should change the “CLK FREQ” and “RST POLARITY” parameters as appropriate.These 4 parameters do some really neat things that I’ll talk about later. If you look online there isn’tmuch info about these parameters and many people are very confused about what they are actuallyused for. This is mostly because if you don’t have them specified the design can still function perfectlywithout them either in hardware or simulation.

You should also note that as of EDK v10.1 sp2 there is * no * support for a CLK POLARITY pa-rameter. Apparently, it did not occur to Xilinx that this parameter would also be useful. When wouldthis be useful you ask? Well, when using differential clocks of course. I recently ran into this issuewhen I was testing a custom IP that utilized a few Multi-Gigabit Transceiver (MGT) ports. In caseyou don’t know MGT ports require a differential clock input in order to transmit/receive a reasonable

1Note that these parameters do not in any way change your hardware design and are only used by EDK’s simulation environ-ment generator tool.

2If you’re clock input is not being routed to a Digital Clock Manager (DCM) then you should just use “CLK” instead of“DCMCLK”.

23

signal on each positive and negative differential port. Differential oscillators will also usually have avery low Parts Per Million (PPM) jitter specification (as is the case with the Xilinx ML325 board). Adifferential clock has two outputs of the exact same frequency except that the clocks are exactly 180degress out of phase. On a Xilinx device these two inputs are usually routes to an IBUFGDS compo-nent as soon as it enters the FPGA. The IBUFGDS block then generates a single output, very clean,reference clock which all of you other internal modules may use. So what am I getting at? Withouta CLK POLARITY parameter EDK will emulate both input clocks as two identical, phase alignedfrequencies. If you input two identical clocks into an IBUFGDS the output reference clock is ’X’ insimulation (this is actually specified in the Xilinx datasheets as well). I spent over an hour trying tofigure out why my design was not simulating properly only to find out that the auto-generated clockinputs were incorrect and none of my logic was receiving a clock!

I have since requested that Xilinx include this parameter as an option to the user and they have agreedthat it was a good idea. The Xilinx Enhancement Request number is 474572. They could not tell meat the time in which revision this enhancement would be integrated but if you want to ask them youhave the number to reference. In the meantime I figured out a way to manually fix the incorrect clockinputs to your design if you are using a differential clock. Here is an example from my design:

The Xilinx EDK auto-generated “system setup.do” script created the following Modelsim commandsfor me:

force -freeze $tbpath${ps}SYS_CLKN_pin 0, 1 {3 ns} -rep 6 nsforce -freeze $tbpath${ps}SYS_CLKP_pin 0, 1 {3 ns} -rep 6 ns

I had to change the command for “SYS CLKN pin” to:

force -freeze $tbpath${ps}SYS_CLKN_pin 1, 0 {3 ns} -rep 6 ns

3. Next, if you are simulating a custom IP core, you will likely want to generate a structural HDLsimulation netlist of your IP. This makes design maintenance much easier because instead of havingto list every single source file in the Xilinx Peripheral Analyze Order (PAO) file for simulation youonly need to include the top-level structural netlist file of your entire core. To generate a simulationnetlist run the following command:

netgen -ofmt <vhdl|verilog> -w <your_toplevel>.ngc

The output of the above command will be a “.vhd” file which you can then add to your PAO file likeso:

simlib <your_ip_library_name> <relative_path>/<your_toplevel>.vhd

Notice that we use “simlib” instead of just “lib” this tells EDK to ignore this file when it is actuallyimplementing the design to be target to the FPGA. However, when it is generating the simulationscripts it will include this file properly.

4. Now, click on the “Simulation” menu at the top of the EDK window and select “Generate SimulationHDL Files”.

24

5. If step 3 was successful, EDK just generated an entire test bench environment for your design com-plete with simulation script macros right at your immediate disposal. To exploit all of the hard workEDK just did click on the “Simulation” menu again and select “Launch HDL Simulator...”. In mycase this opens ModelSim. I have noticed that this sometimes does not open ModelSim on certaincomputers. I haven’t been able to figure out why yet, but if it happens, you can exactly replicate theactions of the “Launch HDL Simulator...” command by performing the following 3 steps:

• Start ModelSim

• Navigate the simulator’s working directory to <your project dir>/simulation/behavioral/

• Run command: do system setup.do

6. Before moving on I would like to note a few changes that may be required to the EDK auto-generatedsimulation files. First, navigate to <your project dir>/simulation/behavioral/ andopen the “simulate.do” file. This is the script that is called when you compile your design. It compileseach of the files that you listed in the Xilinx PAO file in your IP repositories “pcores/¡core name¿/data”directory. The only reason you may need to change this is if you are simulating your design using theglbl.v module provided by Xilinx. If so, you should add the following line to the file:

vlog -work work vlog $env(XILINX)/verilog/src/glbl.v

7. In addition, if you are using any Xilinx core components you will also need to modify the “sys-tem setup.do” file in order to tell modelsim to include the Xilinx simulation libraries. To do thischange file as follows:

Original auto-generated system setup.do:

alias s "vsim -t ps system conf; set xcmds 1"

Add the Xilinx simulation libraries like this:

alias s "vsim -t ps -L unisims ver -L simprims ver -L xilinxcorelib versystem conf; set xcmds 1"

Since most of my designs also use the glbl.v module (in order to emulate the GTS/GSR signals withinthe FPGA) I also modified the line as follows:

alias s "vsim -t ps -L unisims ver -L simprims ver -L xilinxcorelib versystem conf glbl; set xcmds 1"

8. The simulator’s console window should now have a help menu displayed (which was created by thesystem setup.do script). You should see 7 possible commands: c, s, l, w, clk, rst, and h. Ifyou don’t see both the ‘clk’ and ‘rst’ commands in the help menu then you did not configure the“SIGIS”, “CLK FREQ”, and/or “RST POLARITY” parameters in the MHS file properly.

The ‘clk’ command was automatically generated by EDK to generate stimulus to your external clockinput with the specified frequency provided by the “CLK FREQ” parameter. It knew which input wasyour clock because of the “SIGIS = [DCM]CLK” parameter. Similarly, EDK created a ’rst’ stimulusto your design’s external reset input based on the “RST POLARITY” parameter. However, the ‘rst’command not only strobes the reset input, but it also runs the ’clk’ stimulus command for you as well.Pretty cool!

25

9. Now that you have an idea of what the commands do, execute command ‘c’ to compile the design.Then run ‘s’ to load the simulation. Then run ‘w’ to load the waveforms into the waveform window.Next, run ‘rst’ which will generate the clock and strobe the top-level reset input that you defined inthe MHS file.

10. The ‘rst’ command only runs the simulation just long enough to strobe the reset input, so you have toexecute one more command to continue your simulation for however long you want. For ModelSim,I just like to use “run -all”, which will run the simulation indefinitely until you tell it to stop.

11. Try simulating our simple UART design in ModelSim and look at the external TX line from theUART. Try to analyze the data and pick out each character from “Hello World!” as it is sent to theterminal.

26

CHAPTER 4

Adding Custom IP To Your EDK Design

This chapter is a work in progress. I have already successfully added custom IP to my design using theXilinx Custom IP wizard, but I don’t have the time to write a detailed tutorial just yet. However, I haveadded some other sections that provide some very useful techniques for which Xilinx does provide anydocumentation (or support for that matter).

4.1 Manually Changing the Number of S/W Accessible User-Registers

This section will instruct you on how to manually change the number of available user register in your designif you find that you need to change them after you’ve already completed the Custom IP Wizard flow.1

Very recently I found myself needing more S/W addressable user registers for my custom IP than I hadoriginally thought when I first ran the Xilinx custom IP wizard. At first I thought the only way to add morewould be to run through the entire IP wizard again from scratch - which is ridiculous. I knew there had tobe a better way and it is actually quite easy. Follow the steps below and you shouldn’t have any problems.2

1. Open the very top-level template file that the custom IP wizard generated. This is usually “pcores/<ip name>/hdl/vhdl/<ip name>.vhd”.Locate the USER NUM CE parameter and change the number to the number of registers you wouldlike.

2. Open the user logic.vhd file in the same directory. Change the slv reg write/read selectsignal vector sizes to match that which you specified with USER NUM CE in the top-level file. Forexample, if you originally had 3 S/W registers and you added just one more you would change thevector widths from (0 to 2) to (0 to 3). In fact, you can get rid of the static constant vectorand replace it with a more maintenance friendly generic from the entity declaration. Change the vectorto this instead so you don’t ever have to worry about it in the future: (0 to C NUM CE-1). Thiswill pull the USER NUM CE from the top-level and use it to size the vector automatically.

1You should know that Xilinx does not support the “manual” edits to the custom IP templates that the IP wizard provides you ifsaid “edits” are outside of the specifically stated “edit here” sections in the templates.

2DISCLAIMER: I have tested these steps with various custom IP and haven’t yet had a problem, but that does not in any waymean that this method is 100% correct and won’t lead to problems with future designs. In other words, use these steps at your ownrisk!

27

3. Add new internal registers to the user logic module to match the new number of user registers (e.g. ifyou originally had 3 S/W registers and you added just one more you would add the following register:slv reg3 : std logic vector(0 to C DWIDTH-1);

4. Update the slv wrte/read ack signal assignments to reflect each of your additional registers. Followingthe examples above:

slv_write_ack <= Bus2IP_WrCE(0) or Bus2IP_WrCE(1) or Bus2IP_WrCE(2);slv_read_ack <= Bus2IP_RdCE(0) or Bus2IP_RdCE(1) or Bus2IP_RdCE(2);

would change to...

slv_write_ack <= Bus2IP_WrCE(0) or Bus2IP_WrCE(1) orBus2IP_WrCE(2) or Bus2IP_WrCE(3);

slv_read_ack <= Bus2IP_RdCE(0) or Bus2IP_RdCE(1) orBus2IP_RdCE(2) or Bus2IP_RdCE(3);

5. Now, update the SLAVE REG WRITE/READ PROC register selection decoders to reflect your newregisters. Don’t forget to update the sensitivity list for SLAVE REG READ PROC!

6. Next, make sure you have enough memory space allocated to your IP within EDK so that you canaccess the new registers. You may not need to perform this step.

7. Finally, you will obviously need to update the template software driver files that Xilinx providedyou when you intially created the Custom IP core (but only if you intend to continue using them).This should be pretty straight forward. The changes required are similar to those for the hardwaretemplates. Just follow the pattern of function definitons and addresses they provide you.

(a) Add additional slave register offsets as necessary to the header file.

(b) Add additional mWrite/ReadSlaveReg functions as necessary to the header file.

(c) Add additional register read/write tests to the IP ”self-test” function as necessary.

4.2 Creating your own MUI Files

One other useful bit of information I can give you for your adventure into EDK custom IP integration is forcreating your own customized configuration window (i.e. the EDK window that pops up when you right-click on an instance in your EDK design and select “Configure IP. . . ”) for your custom Intellectual Property(IP). The configuration windows are dynamically generated with a very simple XML-syntax file with theextension “.mui”. This file should be stored in the “pcores/<ip name here>/data/” directoryalong with the Peripheral Analyze Order (PAO) and Microprocessor Peripheral Description (MPD) files. Iwill not explain how to edit them but you can learn very easily by looking at some of the MUI files for anyof Xilinx’s IP cores in the EDK install directory. Here are a couple examples:

• A simple MUI -<EDK install dir>/hw/XilinxProcessorIPLib/pcores/opb uartlite v1 00 b/data

• A complex MUI -<EDK install dir>/hw/XilinxProcessorIPLib/pcores/opb emc v2 00 a/data

28