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.1.02i and SDK version 8.1.0
• Xilinx ISE 8.1.03i
• Opal Kelly XEM3010-1500 and FrontPanel 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. First, 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. Finally, the project is exported to an ISE design.
• Part II: The second part involves making some modifications to the ISE project. The top level stub file needs to be connected to the Opal Kelly HostInterface, the Opal Kelly component Library needs to be added, the UCF file must be updated and included, and then the programming file is generated.
• Part III: With the 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. Next, the bit file and block memory map file are imported from the ISE project and are combined with the software executable from the SDK project 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: In this final section, simulation libraries and design files will be generated by Xilinx Platform Studio. A simulation stub file and test fixture are 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 communication through FrontPanel.
• 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 \XilinxEDK\Sample1\system.xmp but you will need your own root location that contains no spaces in the structure.
   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. When done, select OK.
      • 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 select Next.
   4. Under Select Board, chose that you would like to create a system for a custom board, then select Next.
   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 8 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. From within XPS, it’s time to makes some 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 Systems 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.
   3. Select the Address Filter in the System Assembly. Change the Base Address of the okMicroInterface_0 to 0×40000000 and High Address to 0x4000FFFF.
   4. 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 = DCMCLK
    PORT sys_rst_pin = sys_rst_s, DIR = I
    PORT ti_clk = ti_clk, DIR = I
    PORT ti_control = ti_control, DIR = I, VEC = [12:0]
    PORT ti_data = ti_data, DIR = IO, VEC = [15:0], THREE_STATE = FALSE
    PORT led = led, DIR = O, VEC = [7:0]

• The MicroBlaze definition needs to have the following line added (you may put this just below the other PORTs listed but before the END):

    PORT INTERRUPT = interrupt

• At the bottom, make sure okMicroInterface settings show:

    BEGIN okMicroInterface
      PARAMETER INSTANCE = okMicroInterface_0
      PARAMETER HW_VER = 1.00.a
      PARAMETER C_BASEADDR = 0x40000000
      PARAMETER C_HIGHADDR = 0x4000FFFF
      BUS_INTERFACE SOPB = mb_opb
      PORT ti_clk = ti_clk
      PORT ti_control = ti_control
      PORT ti_data = ti_data
      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 system.mhs file.

1. Now lets make some project setting alterations:
2. Select Project → Project Options. Under the Hierarchy and Flow tab, select Processor Design is a sub-module. Change the top level instance name to microcore. Also, Use Project Navigator Implementation Flow should have been automatically selected with a good default location. Select OK.
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. Otherwise, interrupts will point to the default handler in the okMicroInterface driver distributed in the Repository. Select OK.
4. Finally, select Project → Export to Project Navigator to setup the ISE project for synthesis.

1. First, copy the necessary files from the proper FrontPanel installation directories to this local project.
   1. Copy all of the *.ngc files from the \FrontPanel\FrontPanelHDL\XilinxISE71_v2 into the local \Work\XilinxEDK\Sample1\projnav directory.
   2. Copy okLibrary_v2.vhd from \FrontPanel\FrontPanelHDL\XilinxISE71_v2 into the local \Work\XilinxEDK\Sample1\hdl directory.
   3. Copy the two *.xco FIFO CoreGen files, ok_system_stub.vhd, and xem3010_edk.ucf from \FrontPanel\FrontPanelHDL\XilinxEDK\Sample1\hdl to the local \Work\XilinxEDK\Sample1\hdl directory.
2. Now, open the system.ise project generated in the \Work\XilinxEDK\Sample1\projnav directory.
   1. Select Project → Add Source and add the five files we added to the \Work\XilinxEDK\Sample1\hdl directory above.
   2. Select the system_stub.vhd file still present in the project, right click with the mouse and select Remove. Now, our ok_system_stub.vhd file is the new top level, but all files have been properly arranged by XPS in the ISE project. Select File → Save Project As... and save this updated ISE project as ok_system.ise. If you don’t do this, every time you alter something within XPS and re-export those changes to ISE, you will overwrite the changes you’ve made above. Of course, if you make a major alteration in XPS like adding a peripheral, you will want to regenerate the project.
   3. Select the new top level file ok_system_stub.vhd in the Source dialog and double click on Generate Programming File in the Processes window. This will generate the local ok_system_stub.bit file in the \XilinxEDK\Sample1\projnav directory. This bit file must still be infused with the executable data that will be placed in the Block RAM used for program storage.

Go back to the XPS application. Several elements will be tied through XPS now to make a C application and the ISE bit file work together.

1. 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 Managed Make C Project and select Next. Make sure that our Sample1\system.xmp is being used, that the Processor is microblaze_0, and deselect Create sample file in project. Select Next again. Name the project SampleApp and hit Finish.
4. Select File → Import and choose File system import. Hit Next. Browse to the installed directory \FrontPanel\FrontPanelHDL\XilinxEDK\Sample1\SDK_projects\SampleApp and then select sampleMain.c, sampleFunctions.c, and microInterface.h. Make sure the Into folder is Sample App. Select Finish.
5. The SDK should have automatically compiled the imported files and created the SampleApp.elf executable file in your local \Work\XilinxEDK\Sample1\SDK_projects\SampleApp\Debug directory. 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 in the console below.
6. 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.
7. Still in the Applications tab, double click on Add Software Application Project...” and give the project the name SampleApp. Right click on SampleApp and make sure Mark to initialize BRAMs is checked. Right click on it again and choose Set Compiler Options. The Application Mode should be Executable, and then you must browse to the SampleApp.elf file generated earlier. It should be in \Work\XilinxEDK\Sample1\SDK_projects\SampleApp\Debug. Select OK.
8. The final step to creating the final bit file! From the top menu choose Project → Import from Project Navigator. Change the bit file to projnav/ok_system_stub.bit and make sure the BMM file is implementation/system_stub_bd.bmm. Select OK. Now select Device Configuration → Update Bitstream. The SampleApp.elf file data is intelligently combined with the imported ok_system_stub.bit file. This creates the final bit file in \Work\XilinxEDK\Sample1\implementation which is called 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. First, open up the FrontPanel application and connect to a XEM3010-1500P. Click on the Configure FPGA icon and navigate to the download.bit file located in your \Sample1\implementation directory. The MicroBlaze core should now be running if the sys_clk1 is correct.
2. Now click on the Load Profile icon and navigate to the EDK_Sample1.xfg file located in the \FrontPanel\FrontPanelHDL\XilinxEDK\Sample1 directory. You may want to copy this profile to your local working directory.
   • 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×07. The second column contains FrontPanel okDigitDisplay dialogs for WireOut endpoints 0×20-0×27. There is a third column with five buttons. Each of these contain a TriggerIn signal on endpoint 0×40 of bit 0-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 Trig2 and Trig3 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 still 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 XPS and once again select Device Configuration → Update Bitstream. Make sure the latest 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 SampleApp should have been made. Under the Main tab, make sure the project is SampleApp and the C/C++ application is Debug/SampleApp.elf. Under the XMD Target Connection, the target connector should be XMD target debug agent, the target type should be MicroBlaze Hardware (OPB_MDM), and the connect command of connect mb 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 sampleMain.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++);

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 to \XilinxSimLib\EDK8.1_mti_se_nt\ISE_Lib, the SmartModels are in \Xilinx81\smartmodel\nt\installed_nt, and the EDK HDL libraries are in \XilinxSimLib\EDK8.1_mti_se_nt\EDK_Lib\.
2. Select Simulation → Generate Simulation HDL Files. XPS will fill the default directory \Work\XilinxEDK\Sample1\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 SampleApp.elf file. However, a few changes will have to be made before we’re ready to simulate.
3. Copy from \FrontPanel\FrontPanelHDL\XilinxEDK\Sample1\simulation\behavioral to this new local simulation folder the following files: ok_system_tf.vhd, ok_system.do, ok_setup.do, and wave.do. Also copy from the local \projnav directory fifo32x512_to_16x1024.vhd and fifo16x1024_to_32x512.vhd to the simulation folder. These two files are simulation models of the Xilinx Coregen FIFO’s used in the ISE project. If you haven’t built the ISE project yet, a copy has been stored in the installed simulation folder above.
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_systemd.do to reflect the location where the Opal Kelly EDK Repository was copied. Also, the location of the EDK simulation libraries will have to be altered as well in ok_systemd.do. Copy over those lines from the correctly generated locations in XPS generated 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 110us into the transcript will run the simulation through a few basic processes.

1. To test code modifications in the SDK project, simply recompile the SampleApp.elf, regenerate the simulation HDL files in XPS, and then recompile and run the simulator with the two alias keys. 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 to export any changes to ISE. All changes will only be in the software SDK. The bit file imported from ISE will remain system.bit in the local \Sample1\implementation. After a change and recompilation in the SDK, quickly select Device Configuration → Update Bitstream to generate a new download.bit.
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. Exporting changes to ISE or rebuilding the simulation files overwrites all exiting files (with same name). If modifying one of these files, be sure to rename the files so your alterations aren’t lost.
4. 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 and type terminal into the command prompt to enable the UART terminal operation.
5. Please share some of your MicroBlaze suggestions or improvements with our forum community.