Linux on Microblaze HOWTO (part I)

This post was written by eli on August 2, 2011
Posted Under: FPGA,Linux kernel,Microblaze

This is part I of my HOWTO on running Linux on Microblaze. The outline is as follows:


This HOWTO goes through the procedures for getting a simple Linux system running on a Xilinx Microblaze processor. The examples are given for an SP605 evaluation board, but almost everything here applies for other FPGAs and boards as well. The Xilinx software version used here is 13.2.

There are quite a few variants on how to get the bitstream and Linux kernel into their right places in the FPGA. The approach taken here is to boot up from the Compact Flash alone by writing a file to it. No bootloader is used in this howto; the SystemACE chip is responsible for loading both the FPGA bitstream and Linux kernel image, and it will do so reading one single (.ace) file. The main advantage of this approach is that there’s no need to set up a boot loader, which is yet another piece of software that can go wrong. The main disadvantage is that a bootloader allows some tweaking of the kernel configuration at boot time, which has to be done by recompiling the kernel otherwise.

The root filesystem is mounted from network (NFS) in this HOWTO.

I’m assuming the following prerequisites:

  • You have the Xilinx tools set up properly, and have managed to compile and run a simple standalone “Hello, World” application with the EDK/SDK (having loaded the code to the FPGA in any way, we’ll get to that)
  • You’ve actually seen the RS-232 console data on a terminal, and feel confident about it (otherwise you may work hard to figure out why everything is stuck, when it’s actually your terminal window’s problem).
  • You’re running on one of the evaluation boards, or know how to set up the processor to work with your own (and have that tested already)
  • Your board has a systemACE flash chip (recent evaluation boards usually do)
  • You have access to a machine running Linux on a computer. Compiling the kernel will require this. The Xilinx tools can be run on whatever’s your cup of tea.
  • You have the ability to read and write files to a Compact Flash. This is most easily done with a simple adapter to a PC computer, which should be available in camera or computer accessories shops. Chances are you have one without necessarily being aware of it.

An outline of the steps

So this is what we’ll do:

  • Set up a Microblaze processor in the Xilinx EDK so it can run Linux.
  • Generate the processor, so an FPGA bitstream is at hand.
  • Export the processor to the Xilinx SDK and compile a dummy C application, so that  necessary metadata files are generated
  • Generate a Device Tree file (.dts) based upon files created by EDK/SDK, and copy it into the Linux kernel sources, so Linux is in sync with the EDK regarding what it’s running on.
  • Configure the kernel and compile it.
  • Create a .ace file from the FPGA bitstream and kernel image just compiled.
  • Set up the Compact Flash card.
  • Boot and hope for good

And of course, certain software tools will need to be downloaded for this. We’ll come to this.

Setting up the processor

If you’re really lazy about this, you can use the minimal processor I’ve generated for the SP605 board. Unzip, double-click system.xmp, and skip to after the bullets below. It will work on that board only, of course.

Otherwise: Start Platform Studio (EDK) and create a new platform, based upon the Wizard’s defaults.

Following a Microblaze on Linux guide, in particular the part regarding minimal hardware requirements, there a need to make sure that the hardware has an MMU with two regions, a timer, an interrupt controller and a UART with an interrupt line. In the platform studio it goes like this:

Starting off with the Wizard’s defaults,

  • Double click “microblaze_0″ on the Ports tab, and set the Linux with MMU preset on the Configuration wizard showing up. This will take care of most settings.
  • Still in the ports view, add an AXI Interrupt Controller (under Clock, Reset and Interrupt in the IP Catalog). Accept default settings. Make a new connection for its irq output, and connect it to the microblaze_0′s interrupt input pin.
  • Pick the RS232_Uart_1 and make a new connection for the interrupt line. Connect that signal to the interrupt controller.
  • Add an AXI Timer/Counter, and accept defaults. Make a new connection for the interrupt, and connect it to the interrupt controller.
  • Connect the interrupts of the Ethernet lite, SPI Flash, IIC SFP, IIC EEPROM, IIC_DVI, and SysACE cores to the interrupt controller as well.

Then generate bitstream, export to SDK, and run the SDK, adopting this hardware platform. The goal of this is to generate a .mss file, which will be needed later. For this to happen, make a new C project (“Hello World” will do just fine) and compile it.

There is no need to “update the bitstream” like with standalone applications: The Linux kernel can take care of itself, without having its entry address hardwired in the FPGA’s block RAM. We’ll use the system.bit, and not the download.bit (even though the latter works too).

Creating a Device Tree file

The purpose of this stage is to generate a .dts file, which is the format expected by the kernel build environment. It informs the kernel about the structure of the processor and its peripherals. The device tree structure is discusses further here.

If you chose to download and use my processor with no changes whatsoever, you can also get my DTS file. Just copy it to arch/microblaze/boot/dts/ in the to-be compiled kernel source tree.

To make your own .dts file, first create a special directory, and make it the working directory of your shell.

The device tree file is generated automatically with the libgen utility with the help of a Tcl script. As of ISE 13.2, this script needs to be loaded separately with git:

bash> git clone git://

This generates a device-tree directory. Another web page explains how to make SDK recognize the script, but I prefer command line for things like this. Another post of mine explains the device tree further.

Copy the system.xml file from the directory to which you exported to SDK (in the “hw” subdirectory), into the current one. Then copy system.mss from the project’s BSP directory. It will have a name like hello_world_bsp_0.

Edit the copy you made of system.mss, so that the BEGIN OS to END part reads

 PARAMETER OS_NAME = device-tree

and not “standalone” for OS.

And then run libgen as follows (make sure it’s in the PATH. The easiest way is to launch a “Xilinx shell” from the EDK’s project menu):

libgen -hw system.xml -lp device-tree -pe microblaze_0 -log libgen.log system.mss

Which generates a xilinx.dts in microblaze_0/libsrc/device-tree_v0_00_x. Copy this file to arch/microblaze/boot/dts/ in the to-be compiled kernel source tree. If you can’t find the file there, and libgen didn’t complain about some error, you may have forgotten to edit system.mss as mentioned just above.

Now let’s go on to compiling the kernel, in part II.

Reader Comments

Delightfully clear and concise explanation.

Written By Terry Cornall on February 28th, 2013 @ 02:10

Hi Eli Biilauer, this a great and complete tutorial. I have a question, can I compile kernel for the Atlys Board (Digilent), it isn’t SystemAceFlash, but I understands it can boot from USB host or Flash Memory.

Written By Martin on November 28th, 2013 @ 04:13


Compiling the Linux kernel is in fact the easier part, and I understand that there’s a PetaLinux (now owned by Xilinx) bundle for this board.

Once Linux has been loaded and launched properly, assuming that the hardware is correctly mapped in the device tree and that the adequate drivers are in place, there’s usually little left to do.

The trick is to get Linux loaded into RAM in the first place. I would suggest looking at how the PetaLinux bundle tackles this. I would expect it to boot from the SPI flash, but I haven’t dug into this.

Written By eli on November 28th, 2013 @ 15:10

Hi Sir ,
I have a problem with device tree generation using XPS (xilinx 14.1 )
I am working with XUPV5LX110T and while generarting dts file ,Iam getting an error stating ” CPU has not connection to Interrupt controller ” . I have added the Xilinx Interrupt controller to the system @XPS . Even then, the error is shown.( Every port is connected )
I have even checked the tcl file that is used to generate dts file , ( Iam not good at TCL ) I tried removing the portion that performs this action .Then it gave out “DRC for intc has not been done ” (not exact error string –)
Please help me .

Written By Sandeep on January 2nd, 2014 @ 16:00

Sorry, I don’t know what went wrong there.

Written By eli on January 2nd, 2014 @ 22:11

Can you explain me ,what is happening at that portion of tcl script ?

Written By Sandeep on January 3rd, 2014 @ 16:16

I’ve never read through that script, so I can’t help you. I suggest contacting Xilinx’ support on this.

Written By eli on January 3rd, 2014 @ 16:20

I have posted my question @xilinx forums , no reply till now,


Written By Sandeep on January 4th, 2014 @ 05:28

Implemented the MB system and built the Kernel sources (xilinx_v3.0) according to your guide on a SP605, the boot process seems to start but goes nowhere after the following message is displayed:

early_printk_console is enabled at 0x40600000
Ramdisk addr 0x00000003, Compiled-in FDT at 0xc02888c8

The only suspicious warning appears on the SDK when I build the device-tree:
WARNING:EDK – : console ip RS232_Uart_1 was not found. This may prevent output
from appearing on the boot console.

Any ideas?

Written By Dr.Fuzzy on February 14th, 2014 @ 19:04

i’m now doing the same thing . Is this HOWTO availiable with SP601? and i have problem with “Setting up the processor”,for i can’t find the options you descirbed.
thank you very much for your sharing!

Written By jerry on March 27th, 2014 @ 07:14


This guide is more than two years old, and both the kernel and the other tools have made a long way.

As for SP601, it doesn’t have an SystemACE interface, so the boot process will have to be completely different. Doesn’t Xilinx supply information about how to boot from the QSPI flash?

Written By eli on March 27th, 2014 @ 12:33

Thanks for your answering!
My goal is to install a linux to microblaze on SP601.As you can see , there is not enough room to realize.So i ‘m now trying uclinux but the interrupt configuration is too complex to understand.
And i really don’t know what to do now.Nothing similar to my task has been found on the Internet.Can you help me to finish it if you are available?
thank you very much!

Written By jerry on March 28th, 2014 @ 10:19


The SPI flash has 8 MB of memory, which is more than enough for a Linux kernel + an initramfs image with some application. Besides, Linux can mount its root filesystem from the LAN using nfs. So if you insist on this not-so-impressive board, you can run whatever you want on it. Not that I understand why you bother…

Anyhow, uCLinux is for processors with no MMU, and has nothing to do with the memory’s size, so I suggest dropping that.

What I would do if I were you is first to see that I can compile a simple standalone (no Linux) “Hello, world” program. Then try to get U-boot compiled and booted into the system (I expect this to be the difficult part). And then get the device tree right and boot Linux.

It’s not going to be easy, I can tell you that. Did I mention partitioning the SPI flash? (Don’t ask me how to do it)

Written By eli on March 28th, 2014 @ 12:45

when I execute the command below on Xilinx Shell,
“libgen -hw system.xml -lp device-tree -pe microblaze_0 -log libgen.log system.mss”

I get an error saying,
“Cannot find MLD file device-tree_v2_1_0.mld for the os device-tree 0.00.x”

Do you have any idea on this?

Written By Jae on July 22nd, 2014 @ 21:47

I had similar problem with the “Cannot find MLD…” error.

In my case the source of problem was an obsolete version of the SDK. Device tree files on the Xilinx`s GitHub is intended for some new 2014.x version.

I had solved the problem like that:

1) Take old repository: “device-tree” (deprecated), not the new “device-tree-xlnx”. Use this URL:

2) I had cloned repository using TortoiseGIT (do not download .zip!). Then I have opened its history and checked out revision, that was tagged like my SDK verion.

3) After check-out this old version there will be corresponding files: “device-tree_v2_1_0.mld” and “device-tree_v2_1_0.tcl”. I had copied them into SDK folder where it intended to be. I do not sure now, it was like EDK/…/sw/lib/… there was multiple “standalone” and “xilkernel” folders there. I created folder according error messsage (where it searches for this files).

Hope it helps.

Written By Denis on October 14th, 2014 @ 20:19


Written By Pravin Khule on September 7th, 2015 @ 07:10

Add a Comment

required, use real name
required, will not be published
optional, your blog address