FrontPanel V3 & MicroBlaze Introduction

This introduction will walk you through the process of creating a MicroBlaze system for an Opal Kelly XEM3010-1500P. The sample OPB peripheral provides communication to the PC via USB and our FrontPanel API. Full behavioral simulation is also established along with hardware debug support through the Xilinx SDK.

The MicroBlaze core is compiled in Xilinx ISE as a stub device to allow top level attachment to the Opal Kelly HostInterface. This in turn allows for other logic in the FPGA fabric external to the MicroBlaze soft core to also utilize the same FrontPanel connection.

Note: This introduction is not intended to be a tutorial on FPGA design or on using Xilinx ISE, EDK, SDK, or ModelSim software. Rather, it was written to help quickly identify the core stages of Xilinx EDK development and to highlight one possible way to implement a connection between FrontPanel and a Xilinx FPGA embedded processor.

• Xilinx EDK containing Xilinx Platform Studio version 8.2.02i and SDK version 8.2.0
• Xilinx ISE 8.2.03i
• Opal Kelly XEM3010-1500 and FrontPanel 3 Software Installation
• Xilinx Platform Cable USB (for JTAG Hardware Debug connection)
• ModelSim 6 SE or PE (for software simulation)

This introduction is divided into five parts:

• Part I: This first part guides you through creating a new design in the Xilinx Platform Studio. Project settings are configured, the main bus is established, peripherals are attached to the bus, the address space is arranged, port connections are made, and project settings are tweaked.
• Part II: The second part involves making an ISE project. We will connect the MicroBlaze system to a top-level file that contains the Opal Kelly HostInterface. Next, the Opal Kelly component Library is added, the UCF file must be updated and included, and then the main programming file is generated.
• Part III: With the main ISE bit file generated, it’s time to create the microprocessor software. In part three, the software libraries and header files are generated, followed by the creation and compilation of a Xilinx SDK project. Finally, back in ISE the programming bit file are updated with the executable data from the SDK to create a final bit file for download to the FPGA.
• Part IV: In part four, the final bit file is downloaded through the FrontPanel application and tested with an XML Virtual Control Panel. Next, from within the Xilinx SDK project, a hardware debugger is launched which, through a Xilinx JTAG module connected to the XEM3010, we can program the FPGA and step through code in the microprocessor core. This can all be done while connected to a FrontPanel XML panel or custom application.
• Part V: Simulation libraries and design files will be generated by Xilinx Platform Studio. A simulation test fixture is designed, and the files necessary for FrontPanel simulation are added. Full behavioral simulation is performed running the code compiled in the SDK project along with pseudo communication to a FrontPanel interface.
• Notes: Random collection of pointers and notes.

1. Launch Xilinx Platform Studio. From now on, it will be referred to as XPS. You will be prompted to create or open an existing project. Choose to create a new project using the Base System Builder wizard. Click OK to launch the BSB Wizard.
   1. Enter a project file location. Default location will be C:\Work\XilinxEDK\FP3Sample1_XPS\system.xmp. Make sure to use a location with no spaces in the location.
   2. Enter the location of the Opal Kelly Xilinx EDK Repository. This should be copied from the installed FrontPanel directory \FrontPanel\FrontPanelHDL\XilinxEDK to a directory structure with no spaces in the name. Default will be C:\Work\XilinxEDK\Repository.
      • If you do not have the files in your FrontPanel installation directory, you may download them from here.
   3. Select that you would like to create a new design, then continue.
   4. Under Select Board, chose that you would like to create a system for a custom board, then continue.
   5. Alter the FPGA device choice to a Spartan 3, XC3S1500, FG320, -4 device. Now click Next.
   6. Change the reference clock frequency and processor bus clock frequency to 65 MHz for now. Make sure that On-chip H/W debug module is selected, the Data and Instruction BRAM usage is 16 KB, No Cache is used, and the FPU is not enabled. Select Next.
   7. No IO devices are being added. Select Next.
   8. No peripherals are being added yet. Select Next.
   9. Disregard any warning about no output ports and select OK.
   10. Make sure the STDIN and STDOUT device is set to debug_module (the H/W debug module added above). You may deselect the sample applications or keep them. Select Next.
   11. Select Generate.
   12. Select Finish.
2. In XPS, it’s time to makes changes to the system assembly.
   1. Under the Project Information Area, select the IP Catalog tab. Under Peripheral Repositories, double click on okMicroInterface. Select Yes to add the IP.
   2. In the System Assembly view, you should now see the okMicroInterface_0 peripheral. With the Bus Interface Filter selected, expand the okMicroInterface_0 peripheral to expose its bus connection. Select the connection and pull down to connect the peripheral to the mp_opb bus. This is the default name given to the OPB bus, which in turn should be connected to the OPB controller and the debug_module.
      • If for some reason the mp_opb controller was not added to your design, manually do so. The DOPB and IOPB bus connections to the MicroBlaze core should also be connected to this bus.
   3. Back in the Project Information Area, select the Project Tab and double click on the system.mhs to open it up. Altering port connections here is easier than doing it in the GUI.
      • At the top of the file near the definition for the two default external PORT pins, alter to the following:

    PORT sys_clk_pin = dcm_clk_s, DIR = I, SIGIS = CLK, CLK_FREQ = 65000000
    PORT sys_rst_pin = sys_rst_s, DIR = I, RST_POLARITY = 0, SIGIS = RST
    PORT ti_clk = ti_clk, DIR = I
    PORT ok1 = ok1, DIR = I, VEC = [30:0]
    PORT ok2 = ok2, DIR = O, VEC = [16:0]
    PORT led = led, DIR = O, VEC = [7:0]

• Just below this, the microblaze block needs to have the following line added (you may put this just below the other PORTs listed but before the END):

    PORT INTERRUPT = interrupt

• Finally, at the bottom of system.mhs, make sure the okmicrointerface block shows:

    BEGIN okmicrointerface
      PARAMETER INSTANCE = okmicrointerface_0
      PARAMETER HW_VER = 3.00.a
      BUS_INTERFACE SOPB = mb_opb
      PARAMETER C_BASEADDR = 0x40000000
      PARAMETER C_HIGHADDR = 0x4000ffff
      PORT ok1 = ok1
      PORT ok2 = ok2
      PORT ti_clk = ti_clk
      PORT led = led
      PORT IP2INTC_Irpt = interrupt
    END

• Hit Ctrl-S to save the changes to the system.mhs file. This will update the design. Close the file.

1. In the System Assembly View, select the Address Filter in the System Assembly. Make sure the Base Address of okMicroInterface_0 is 0×40000000 and the High Address is 0x4000FFFF.
2. Now lets change some general project setting.
3. Select Software → Software Platform Settings.
   • With Software Platform selected on the left, under Processor Parameters change the current value of CORE_CLOCK_FREQ_HS to 65000000 and change xmdstub_peripheral to none. The processor won’t boot properly unless you remove the debug_module from the xmdstub_peripheral.
   • With Interrupt Handlers selected on the left, change the Interrupt Handler for IP2INTC_Irpt to Test_Interrupt. This will point the interrupt routine to the function Test_Interrupt in our SDK project. Select OK.

1. Begin by creating a new ISE Project. The default location is C:\Work\XilinxEDK\FP3Example_ISE\ISE_Proj.ise
2. From the FrontPanel installation directory, copy all of the *.ngc files and okLibrary.vhd from \FrontPanel\FrontPanelHDL\XilinxISE82\ into the local ...\FR3Example_ISE directory.
3. Copy the two *.xco FIFO CoreGen files from the here to ...\FR3Example_ISE as well.
4. From the same archive, copy ok_system_stub.vhd, and xem3010_edk.ucf to XPS data directory at C:\Work\XilinxEDK\FP3Sample_XPS\data.
5. In ISE, it’s time to start adding the sources.
   1. Selecting Project → Add Source, add the five files we added above to the project. These should be okLibrary.vhd, fifo16_to_32_fwft.xco, fifo32_to_16.xco, ok_system_stub.vhd, and xem3010_edk.ucf/
   2. Add the XPS file system.xmp file in the C:\Work\XilinxEDK\FP3Sample_XPS directory to ISE as a source as well.
   3. The file ok_system_stub.vhd should have been setup as the toplevel file. Select this file an double click on Generate Programming File underneath the Processes menu. You will be asked to recompile the Coregen FIFOs.
      • If the FIFO’s do not build, you may have an IP mismatch between ISE versions. Select one of these FIFO Coregen modules and then in the Processes window double-click Manage Cores to work with the XCO files.
      • Manage Cores will open the Xilinx CORE Generator. These FIFOs were originally FIFO Coregen Version 3.2. If you have newer or older IP, you may need to recustomize them here to update the files. You may also change the size of the FIFO to better fit your design. Doing so might change the size of some of the status registers and they will have to be altered in user_logic.vhd file in the okMicroInterface peripheral.
      • Building the programming file will generate the local ok_system_stub.bit file in the C:\Work\XilinxEDK\FP3Sample_ISEdirectory. This bit file must still be infused with the executable data that will be placed in the Block RAM used for program storage.

1. Back in XPS, select Software → Generate Libraries and BSPs. This will, among other things, generate the libraries and header files necessary to build an application.
2. Select Software → Launch Platform Studio SDK.
3. Within the SDK, select File → New Project if the wizard hasn’t already started. Under C, choose C Application Project with automatic Makefile and select Next. Name the project FP3Sample_SDK and hit Finish.
4. Right-Click on the project name and select Properties. Under C/C++ Build, change Configuration to Release. Select OK.
5. Extract the file in the archive in folder FP3Sample_SDK a temporary folder. In the SDK, select File → Import and choose File system. Hit Next. Browse to your temporary folder and then select main.c, sampleFunctions.c, and microInterface.h. Make sure the Into folder is FP3Sample_SDK. Select Finish. Ignore any overwrite warnings.
6. The SDK should have automatically compiled the imported files and created the FP3Sample_SDK.elf executable file. The default settings for the SDK is to rebuild the application automatically on any file save or addition. In any case, make sure the application has been built properly.
7. Returning to XPS, in the Project Information Area, select the Applications tab. Right click on each of the projects here and make sure none of them have a check mark by Mark to initialize BRAMs.
8. Still in the Applications tab, double click on Add Software Application Project...” and give the project the name FP3Sample_SDK. Check the Project is an ELF-only Project box and browse to your new .elf file in C:\Work\XilinxEDK\FP3Sample_XPS\SDK_projects\FP3Sample_SDK\Release. Select OK.
9. Right click on FP3Sample_SDKand make sure Mark to initialize BRAMs is checked.
10. The final step to creating the final bit file! Go back to your ISE project. From the Processes window, double click on Update Bitstream with Processor Data.
    • The FP3Sample_SDK.elf file data is intelligently combined with the ok_system_stub.bit file. This creates the final bit file in ISE project directory called ok_system_stub_download.bit. This file will boot this MicroBlaze core in a XEM3010-1500P and run the executable code we compiled.

We’re now ready to start working with the MicroBlaze system.

1. Open up the FrontPanel application and connect to a XEM3010-1500P. Click on the Configure FPGA icon and navigate to ok_system_stub_download.bit. The MicroBlaze core should now be running if the sys_clk1 is correct.
2. Click on the Load Profile icon and navigate to the FP3Sample_EDK.xfp file. You can find this file in the main archive.
   • If the PLL settings in the EEPROM on the XEM3010 had the sys_clk1 running too quickly for the MicroBlaze core, it may not have booted properly. However, loading the sample profile updated the PLL setting so now sys_clk1 should be running at 65Mhz. To be sure, click the switch S1 on the XEM3010 to reset the MicroBlaze processor. You should see a sweep of the LED’s which is a function call at the beginning of the embedded C code. To insure that sys_clk1 is always 65MHz when you first reconfigure the device, save the current PLL settings to the EEPROM. Open the PLL dialog within FrontPanel and click EEPROM Write.
3. Looking at the loaded profile, we have two columns of hex characters. The first column contains FrontPanel okDigitEntry dialogs for WireIn endpoints 0×00-0×05. The second column contains FrontPanel okDigitDisplay dialogs for WireOut endpoints 0×20-0×25. There is a third column with four trigger buttons. Each of these contain a TriggerIn signal on endpoint 0×40 of bit 1-4 respectively. You can play around with this dialog, but by examining the C code in our SDK project, you will see that WireIn 0×00-0×05 are sampled and relayed to WireOut 0×00-0×05, WireIn 0 has it’s lower 8-bits connect to the LED’s, and Trig1-3 activate interrupt routines that call the LED sweep with different delays.

Now hardware debugging will be performed with a Xilinx Platform Cable USB, the JTAG header on the XEM3010, the ODP Hardware Debug Module (debug_module) built into the MicroBlaze core, and Xilinx SDK all working in concert.

1. Go back to XPS and select Debug → XMD Debug Options. Make sure that under Connection Type that Hardware is selected and then click on Save.
2. Within the SDK, select Project → Properties. Make sure your Configuration mode is Debug, the Optimization Level” is set to “No Optimization, and the Debug Level has Generate Debug symbols (-g) enabled. Rebuild the .elf file if anything has changed and go back to ISE and once again double-click under Processes the option Update Bitstream with Processor Data. You may need to right-click on this option and select Re-run to make it fully process (ISE doesn’t always detect changes in the XPS or SDK projects correctly). Make sure the latest ok_system_stub_download.bit is configured in the XEM3010 with FrontPanel.
3. In addition to having FrontPanel opened and connected to the MicroBlaze core through USB, make sure you have a Xilinx JTAG cable connected to your PC and the JTAG header on the XEM3010.
4. Back in the SDK, select Run → Debug. Make sure the configuration Xilinx C/C++ ELF is selected, along with the Perspectives Debug: Debug and Run: None. Click New.
5. A new configuration called FP3Sample_SDK should have been made. Under the Main tab, make sure the project is FP3Sample_SDK and the C/C++ Application is Debug/FP3Sample_SDK.elf. Under the XMD Target Connection tab, the target connector should be XMD target debug agent, and the target type should be MicroBlaze Hardware (OPB_MDM). Click Apply followed by Debug.
6. If the SDK asks if you want to change to a Debug perspective, select Yes. We are now hardware debugging the SDK Sample project and should be frozen near the top of main.c Select Run → Resume to continue processing. You may now set break points, make changes in the FrontPanel XML profile while tracing changes in the Debug SDK, etc. Enjoy your debugging.

If you have ModelSim 6 SE or PE, XPS can generate simulation files directly. If you have another simulator such as Aldec ActiveHDL, simulation is still possible but will require more work. Check with your tool provider for more assistance. For a more detailed explanation of how FrontPanel Simulation works, please see Part IV of the online tutorial here.

Before beginning, a free license and installation of IBM CoreConnect is required. This small package allows IBM Bus Functional Models (BFM) to be generated. IBM owns some of the bus technology used in these embedded processors, so this is required. Search Xilinx.com for IBM CoreConnect to find the latest link for registration and download the BFM package.

Also, the Flash_LEDs function in the SDK project has a long delay count which would take exceedingly long in simulation. The easiest way to alleviate this is to comment out the delay line:

//for (count = 0; count < Delay; count++);

or simply removed calls to Flash_LEDs (or pass in the number 0 to see a quick sweep in simulation).

Save this change and rebuild the application.

1. Back in XPS, the first thing to do is to generate the simulation libraries. Select Simulation → Compile Simulation Libraries.... This will launch a wizard which will take you through the process. In this sample, only VHDL is used.
   • For reference, our ISE HDL libraries are compiled in C:/Installed/SimLibs/ISE/, the SmartModels are in \Xilinx81\smartmodel\nt\installed_nt, and the EDK HDL libraries are in C:/Installed/SimLibs/EDK/.
2. Select Simulation → Generate Simulation HDL Files. XPS will fill the default directory C:\Work\XilinxEDK\FP3Sample_XPS\simulation\behavioral with most of the files necessary for simulation, along with a few do files that aid in the compilation and instantiation of the simulation. The file system_init.vhd contains the Block RAM initialization information derived from the latest FP3Sample_SDK.elf file. However, a few changes will have to be made before we’re ready to simulate.
3. Copy from all the files from \simulation\behavioral in the archive to this new local behavioral simulation folder. You should copy: ok_system_tf.vhd, ok_system.do, ok_setup.do, wave.do, fifo32_to_16_fwft.vhd, and fifo32_to_16.vhd.
   • Ideally, you would retrieve the FIFO *.vhd files from your ISE project folder. These are simulation files for the Coregen’ed FIFOs. They should be compiled (use Manage Cores in ISE) to be structural simulation files. Xilinx behavioral models for FIFOs are not cycle accurate. The files included are structural Xilinx IP FIFO’s version 3.2 and they work well in a behavioral simulation.
4. The file ok_system.do is a superset of the commands in the XPS generated system.do, while ok_setup.do is basically a simplified and modified system_setup.do.
   • The locations to user_logic.vhd and okMicroInterface.vhd will have to be edited in ok_system.do to reflect the location where the Opal Kelly EDK Repository was copied. The location to the EDK simulation libraries will have to be altered as well. Copy these lines from the correctly generated locations in XPS generated system.do.
   • If IP versions in ISE or the EDK change, transfer these changes from system.do to ok_system.do.
5. Launch ModelSim and select File → Change Directory to navigate to this local behavioral simulation directory. ModelSim should already be setup to locate the Opal Kelly Simulation Libraries. See the tutorial linked to above for help on this. In the Transcript window, enter

    do ok_setup.do

• This will setup alias commands. Entering c into the transcript will now process ok_system.do and entering s with start the simulation and open the waveform settings detailed in wave.do. Enter both of these commands, one at a time, in order now. The simulation should be initialized and ready to run. Typing run 670us into the transcript will run the simulation through a few basic processes.
• The alias o was created to just recompiled the test fixture, ok_system_tf.vhd. If you are only making changes to this file, rerun simulation by running o and then s consecutively in the transcript.

1. To test code modifications in the SDK project, simply recompile the FP3Sample_SDK.elf, regenerate the simulation HDL files in XPS, and then recompile and run the simulator with the two main alias keys, c and s. We are now free to simulate not just code modifications in the SDK that run on the MicroBlaze processor, but also to make changes in the ok_system_tf.vhd file to simulate how a FrontPanel PC application with interface to the core through our OPB peripheral.

Below is a collection of tips for improving the work flow of the entire EDK suite.

1. Once you’ve built an ISE bit file, unless there are hardware changes in XPS, you will never have rebuild the main ok_system_stub.bit file. All changes will only be in the software SDK. This same bit file is simply initialized with the bit steam from the SDK .elf file within ISE. After any change and recompilation in the SDK, go back to ISE, double-click under Processes the option Update Bitstream with Processor Data. You may need to right-click on this option and select Re-run to make it fully process (ISE doesn’t always detect changes in the XPS or SDK projects correctly).
2. If any hardware, addressing, or software linking changes occur, use Software → Generate Libraries and BSPs followed by a recompilation of your software in the SDK.
3. The hardware debug module, in addition to providing debug support, is also setup by default as a STDIN and STDOUT device with UART enabled. From within the SDK Debug environment, open the XMD Console to see messages sent with the print command. For instance, clicking on Trig 0×40 (4) will output the message “ISR 4”. If you do not have a hardware debug module connected to the MicroBlaze core and repeatedly hit this trigger, the output buffer will overflow and lock the processor. Of course, this can be prevented in code.
4. Please share some of your MicroBlaze suggestions or improvements with our forum community.