wiki:Exercises/13_4/IntroToXPS

Introduction to the Xilinx Platform Studio (XPS)

(compatible with WARP v3)

In this exercise, users will be introduced to the Xilinx Platform Studio (XPS). This tool is used by designers to build complete systems out of separate peripheral cores known as "pcores." In this exercise, user's will extend a provided template project by adding a custom pcore that implements a pseudorandom number generator (PRNG) directly in the FPGA. This core is then connected to the template project's User I/O core so it can drive random values out to LEDs and hexadecimal displays.

Prerequisites

  • You have a WARP v3 board
  • ESD protection for the WARP board (wrist strap, etc)
  • External USB JTAG cable and a micro USB cable for UART
  • Complete installation of ISE System Edition 13.4
  • Checked out a local copy of the WARP Repository
  • Set up a terminal on your computer using PuTTY or an alternative.
  • Familiarity with the Xilinx SDK. Make sure you have completed the Introduction to the SDK exercise.

Overview

In this exercise, we provide users with a custom peripheral core: the prng_useriosrc. This core is a pseudorandom number generator with ports that are meant to be connected to the User I/O core that is present in the template WARP design. The above figure describes is a simplified diagram of the final after adding the custom pcore. Inside the custom core there is a Linear Feedback Shift Register (LFSR) that produces a sequence of pseudorandom values. These values are then latched by a counter circuit to slow them down and make their changes visible to the naked eye when observing a board. The output of this latch is sliced up and connected to output ports on the core. All pcores have two distinct ways of getting information into and out of the peripheral:

  • Ports: Shown in yellow in the above figure, ports allow direct connectivity between peripherals. They can serve as inputs or outputs of the design.
  • Registers: Shown in red in the above figure, registers allow peripherals to be controlled by software running in a Microblaze soft processor. Registers allow the core to hang off a bus such as the Processor Local Bus (PLB) and allow custom C-code to read or write memory addresses to control the core.

The prng_useriosrc pcore has the following inputs and outputs:

Inputs

  • User I/O Pushbutton Port: This port is connected directly to the User I/O "up" pushbutton port. When the user presses the button on the board, the latch inside the prng_useriosrc core will stop updating the outputs. This will effectively "pause" the core and allow the user to read the current set of outputs from the LEDs and other display elements.
  • Capture Period Register: This register attaches to the bus and allows C-code executing inside the MicroBlaze to control how often the latch on the LFSR triggers. In effect, this is a way for C-code to control how fast the output updates occur. Note: even though we have listed this as an input to the core, this register can also be read by the C-code in order to check and see what it had been set to.

Outputs

  • Left/Right Hex Display Ports: The left and right hexadecimal displays contain seven individual on/off segments. These output ports drive 7-bit wide random numbers to the equivalent input ports on the User I/O core.
  • Red/Green LED Ports: The banks of red and green LEDs each contain 4 elements. These 4-bit wide random numbers drive the equivalent input ports on the User I/O core.
  • Captured Output Register: This register attaches to the bus and allows C-code executing inside the MicroBlaze to read the current latched output of the LFSR.

You will also notice in the diagram the green "FPGA Pins" ports. These are top-level ports that are routed out to physical pins on the FPGA. These pins are connected to other components on the WARP board. For the purpose of this exercise, we have provided this pcore as an example of a hardware peripheral you may want to integrate into your design. The Exporting pcores from System Generator exercise covers how this pcore was created.

Instructions

  1. Download either the WARP v3 Template Project. Note: We recommend using the "lite" template for this exercise as it will build the quickest.
  2. Extract the archive into a folder on your hard drive. Note: this folder must not contain any spaces in the path (this includes the the Windows desktop, as that lives in a folder known as "Documents and Settings").
  3. Navigate to this folder in Windows Explorer. Go into the SDK_workspace folder. These are the default SDK projects used in the Introduction to SDK exercise. We do not need them for this exercise. Delete the three folders in SDK_workspace (but do not delete SDK_workspace itself).
  4. Download the provided pcore. Unzip the archive and place the "prng_useriosrc_plbw_v1_02_a" folder inside the "pcores" folder in the extracted template project.
  5. Launch XPS from the Start menu. Click "Open project" and navigate to the system.xmp file from the template project. Click Open.
    • If this is the first time you have run XPS, you will receive a number of error messages saying that cores cannot be found. XPS must be told where to find the WARP SVN repository in order for it to find these files. In XPS, click Edit→Preferences. Then, under the "Application" category, click "Browse ..." under the "Global Peripheral Repository Search Path." Navigate to and select the "edk_user_repository" folder on your hard drive. If you do not have an "edk_user_repository" SVN working copy, please see our SVN documentation. After making this selection, close and reopen XPS. This step of adding the global repository path only needs to be done once per installation of the Xilinx tools.
  6. To connect the new pcore to the system, we will modify the Microprocessor Hardware Specification "system.mhs" You can find this file in the "Project" tab under "Project Files." Double-click this file to open it.

  1. Add the following chunk of code to the bottom of the system.mhs file:
BEGIN prng_useriosrc_plbw
 PARAMETER INSTANCE = prng_useriosrc_plbw_0
 PARAMETER HW_VER = 1.02.a
 PARAMETER C_BASEADDR = 0xc4000000
 PARAMETER C_HIGHADDR = 0xc400ffff
 BUS_INTERFACE SPLB = plb_secondary_80MHz
 PORT sysgen_clk = clk_80MHz
 PORT hexdisp_left = LeftHexDisplay
 PORT hexdisp_right = RightHexDisplay
 PORT leds_green = GreenLEDs
 PORT leds_red = RedLEDs
 PORT pause = UpPushbutton
END

This chunk of code will instantiate the prng_useriosrc core in the design and attaches it to the bus (here, the plb_secondary_80MHz bus). Additionally, it attaches the input/output ports of core to some unique net names (LeftHexDisplay, RightHexDisplay, GreenLEDs, RedLEDs, and UpPushbutton). These net names are arbitrary; the important thing is that the names match on the corresponding ports to whatever the core is connected to.

  1. Find the chunk of code that starts with "BEGIN w3_userio." Before the "END" line, add the following port connections:
 PORT usr_hexdisp_left = LeftHexDisplay
 PORT usr_hexdisp_right = RightHexDisplay
 PORT usr_leds_green = GreenLEDs
 PORT usr_leds_red = RedLEDs
 PORT usr_pb_u = UpPushbutton

This connects the ports from the prng_useriosrc_plbw to the appropriate ports on the User I/O core. Click File→Save. You will be asked if you want to reload the project; click "Reload." At this point, you may wonder how you are supposed to know the names of ports themselves. Unfortunately, ports that are floating (i.e. disconnected) do not show up in the system.mhs file. The best way to find a full list of all ports a pcore has is by looking at its entry in the "System Assembly View" tab. In the next step, we'll be looking at this view to verify that the prng_useriosrc pcore is correctly hooked up to the system.

  1. Open the System Assembly View tab and make sure you are looking at the "Bus Interfaces" subtab. To the left of prng_useriosrc_plbw_0, you see a yellow circle connecting the core to the plb_secondary_80MHz bus. Unconnected pcores show an empty, white circle.

  1. Next, click on the "Ports" subtab. Click the + next to the w3_userio_0 core and the prng_useriosrc_plbw_0 core. The names shown next to the port are not the arbitrary net names we gave earlier (e.g. LeftHexDisplay). Instead, this GUI shows what core each port is connected. It should look like this:

  1. Finally, click the "Addresses" subtab. In the bottom of the window, you will see the prng_useriosrc_plbw_0 core belongs to a class of "Unmapped Addresses." Each register needs to be mapped to a memory address in order for the C-code in the MicroBlaze to be able to read or write to it. Simply click the button in the upper right of the window to "Generate Addresses."

If successful, the "Unmapped Addresses" grouping will disappear and prng_useriosrc_plbw_0 will join the rest of the cores in the MicroBlaze's memory map.

  1. Now click the "Generate BitStream" on the far left of the window. This will take ~10 minutes on a fast computer.
  2. Once the project has finished generating the BitStream, click the "Export Design" button with the SDK logo on the far left of the window. Then click "Export & Launch SDK."
  3. The SDK will launch and will pull up a window for you to select your workspace. Navigate to the SDK_workspace folder you cleared out at the beginning of these instructions. Then click "OK."
  4. The SDK will now open and will have one project: the "_hw_platform" from the hardware design from XPS. You might recall from the Introduction to SDK exercise that two other software projects are needed to be able to run this design on the board: a Board Support Package (BSP) and a top-level software project. We will create these manually rather than import existing ones like in the Introduction to SDK exercise.
  5. Rather strangely, the Xilinx SDK does not automatically know about software drivers to custom peripherals in your XPS project. You have to explicitly tell the SDK where to find your hardware project. This is a step you have to do with every new SDK workspace. In this exercise, we do not have any custom peripherals, but it is still a good habit to get into. Click on the "Xilinx Tools" menu item and select "Repositories." Here, you want to ensure two things:
    • In Local Repositories, you want to point the SDK to the folder that contains the XPS project system.xmp file. Click on "New..." and navigate to and select this folder.
    • In Global Repositories, you want the SDK to point to the edk_user_repository folder on your hard drive. Unlike the local repositories, the SDK does remember this setting across workspaces. You'll only need to manually add the edk_user_repository the first time you run the SDK.
  6. Click the "New" button in the top left of the window.

  1. Click on "Xilinx Board Support Package" and click "Next."
  2. Click "Finish."
  3. A new window will pop-up that allows you configure the BSP with various optional software packages. For the purposes of this exercise, the default settings are fine. Just click OK. You will see the console at the bottom of the screen start printing messages as the SDK compiles the BSP. It will end up with "Finished building libraries" printed to the console.
  4. We're now ready build the actual software project that will control our custom core. Click the same "new" button above the "Project Explorer."
  5. Click "Xilinx C Project" and then click "Next."
  6. Click "Empty Application" under the "Select Project Template" dialog. This will rename the project to "empty_application_0." Change that name to "example_project." Click "Next."
  7. We have already created a BSP, so we do not want this dialog box to make another one for us. Click the radio button next to "Target an existing Board Support Package." Click "Finish"
  8. Download prng_example.c to somewhere on your harddrive.
  9. In the Project Explorer on the left side of the SDK, you will see the example_project_0 project. Click the + next to it and it will reveal a "src" folder. Drag the prng_example.c file from Windows explorer into this src folder. The project will immediately build. You can look through this C-code and see how it is different than the C-code that was provided in the template project and was used in the previous Introduction to SDK exercise. The differences are commented.
  10. Follow the same steps as in Introduction to SDK to generate a new linker script and download the design to the board.

Testing the Design

When you download the design and run the software, you should immediately see the LEDs and hexadecimal displays start blinking randomly since they are being driven by the LFSR that is in this code.

When you press the "up" pushbotton of the top left of the board, you should see the User I/O LEDs and hexadecimal displays "pause" their current state.

As you press the button, your serial terminal on your computer will also print out the current state of the captured output register from the custom core.

WARP v3 Template Project - Lite
Board serial number: W3-a-00006

Running User I/O Example
                    Left Hex  -------------     -------------  Right Hex
                    Red LEDs  -------                 -------  Green LEDs
        PRNG Captured Value:  1 1 1 0 1 1 1 0 1 1 1 1 0 1 0 0

You can verify that the LEDs match the contents of the register. For example, in the earlier screenshot, the second green LED is illuminated and the last sequence of bits out of the PRNG captured value is "0 1 0 0." The first three red LEDs are illuminated and the first sequence of bits from the PRNG captured value register are "1 1 1 0."

Discussion

The purpose of this exercise to show how data can get into and out of a custom core: through hardware ports and registers. While we used the User I/O core as the sources and sinks of the ports from the PRNG core, this process is fundamentally no different than I and Q samples being sent to and received from the radio bridge. The custom core we connected to the system in this exercise is a proxy for a custom physical layer-- the process is the same.

Additional Questions and Feedback

If you have any additional questions about this exercise or other feedback, please post to the WARP Forums.

Last modified 6 years ago Last modified on Apr 24, 2013, 10:11:16 AM

Attachments (9)

Download all attachments as: .zip