Table of Contents
The goal of this page is to help users understand how to get the MicroBlaze Linux kernel source code, build it and run it on a Xilinx board. The Microblaze architecture was accepted into the mainline kernel and is in 2.6.31. It is contained in the linux-xlnx repository of the Xilinx GIT server.
Everything on this site assumes building a Linux Kernel with MMU only as Xilinx is not supporting the non-MMU kernel. The MicroBlaze Linux kernel does not use a bootstrap loader to decompress the kernel. If users want to run a compressed kernel, they need to provide their own loader which uncompresses it, such as u-boot.
This site assumes that those testing the Linux kernel on MicroBlaze are knowledgable of Embedded Linux. It is not intended to be tutorial on Linux.
Tested Hardware and Reference Systems
The 1st test platform was the ML507 from Xilinx. The kernel has been ran on the other boards, the Spartan 3ADSP1800 board and the ML505 board, but is not currently being tested on them. Early testing with the ML605 and the SP605 boards has also started with good success.
A reference design for the Xilinx ML507 is contained in a file, ml507_mb_v1_system.tar.bz, can be downloaded at the following location.
This reference system should allow users to get a baseline up and running quick and easy. NOTE: This system is not intended to be a high performance design for benchmarking the kernel.
The SP605 is now the current test platform. A reference design is provided by Xilinx at the following location.
This system has been tested on the SP605 with Linux with Xilinx tools up to and including 12.2.
Minimum Kernel Hardware Requirements
The following items must be present in the hardware system for the MMU based Linux kernel. Xilinx does not support the non-MMU kernel for MicroBlaze.
- The MMU in virtual mode and 2 memory protection zones
- A timer (xps_timer core) which has both timers in it (C_ONE_TIMER_ONLY=0)
- A UART for the console, either UARTLite or UART 16550
- Interrupt Controller with the timer and UART connected
See the device driver page that is common for the PowerPC and Microblaze Linux kernel at OSL Device Drivers.
Known Issues & Limitations
Past Resolved Issues
If you use busybox with UNIX98 ptys enabled, telnetd will give an error and not work with incoming telnet connections. You must disable this feature in busybox and then create the ptyp0 and ttyp0 devices manually in the root file system. See Documentation/devices.txt for the device node information (ptyp0 = c 2 0, ttyp0 = c 3 0).
Current Issues & Limitations
MicroBlaze Versions With Caching
MicroBlaze version 7.20c has problems with write back caches such that 7.20d must be used.
Version 7.20c also has some problems with write through caches that are not obvious. If the DCACHE_ALWAYS parameter is set on the MicroBlaze, then there can be issues when mixing cached and non-cached memory. This problem can be see with USB Host and when using non-cached buffer descriptors with the LL TEMAC.
It's safest to use 7.20d which will be released in 11.4 Xilinx tools.
LL TEMAC On Spartan3ADSP1800 At Gigabit
The LL TEMAC driver must be setup in the kernel configuration (under the LL TEMAC driver) to use "other PHY" PHY Support in order to work at gigabit rate. It will work fine at 100 Mbit using the GMII selection under PHY Support.
The kernel is not fully preemptible yet. The kernel configuration reflects this and setting the kernel configuration to full preemption does not fix that as the kernel still needs more work in this area. For some drivers that are poorly designed, it can break them. The old I2C driver that's in the Xilinx tree had to be changed as it had udelays waiting for interrupts and that doesn't work. The udelays were replaced with schedule_timeout_interruptible which is probably the right solution anyway.
The new MicroBlaze kernel uses device tree which is very similar to the PowerPC Linux kernel. The device tree describes the hardware system such that the kernel can configure itself during boot. The device tree generator can be pulled from the Xilinx GIT repository at git://git.xilinx.com/device-tree.git. See the following page for more information about the process, Device Tree Generator.
MicroBlaze GNU Tools
See the following page, MicroBlaze GNU Tools, for information about getting the GNU Tools for Microblaze to build the Linux kernel and applications.
Prebuilt Ramdisk Image
A ramdisk image, initramfs_minimal.cpio.gz, is provided in a tar file of the xldk/microblaze_v1.0 repository of the Xilinx Git server. The repository contains the MicroBlaze GNU tools and the ramdisk image. See the following page MicroBlaze Tools for more details.
Save the ramdisk file from the tar file into the root of the kernel directory as the default kernel configurations for Xilinx (xilinx_mmu_deconfig) expects it to be located there. This ramdisk image is built from busybox and has telnet enabled such that if you have ethernet you can telnet to the kernel.
The MicroBlaze Linux kernel is not using the initrd ramdisk image as we currently use on the PowerPC Linux kernel. It is using an initramfs ramdisk which has a different build process. The kernel command line does not require "root=/dev/ram" for the initramfs. Two jumping off, pre-built ramdisks are provided; one without the support shared libraries contained within it called initramfs_minimal.cpio.gz and one with them included called initramfs_complete.cpio.gz.
Refer to the text file, Documentation/filesystems/ramfs-rootfs-initramfs.txt, in the kernel tree for more details about initramfs. The kernel configuration includes a configuration item, CONFIG_INITRAMFS_SOURCE, that can be setup to point to a cpio archive or a directory where a cpio archive is to be built.
The Linux Kernel For MicroBlaze
Getting the Kernel From Xilinx
The following command gets the kernel tree from the Xilinx Git server.
bash> git clone git://git.xilinx.com/linux-xlnx.git master
Configuring The Kernel
Configuration of the kernel is done in the same manner as any other Linux kernel. The kernel should be configured to a known configuration before building it.
bash> make ARCH=microblaze menuconfig
There is a default kernel configuration file provided with the kernel for the ML507 reference design provided on this wiki.
bash> make ARCH=microblaze xilinx_mmu_defconfig
Kernel Configuration Details
A significant difference with the MicroBlaze Linux kernel configuration is that it must contain parameters to match the processor hardware configuration (barrel shifter, multiplier, etc). This is because the GCC must be passed flags when the kernel is built to build code that matches the processor hardware.
From the top level menu in the kernel configuation, select "Platform options" such that a menu similar as shown below is displayed. The values in this menu should match the values for the Microblaze in the device tree file which was generated from the EDK project.
Building The Linux Kernel
Building the kernel is done in a similar manner as the PowerPC kernel. The result of building the kernel is an elf file in arch/microblaze/boot named simpleImage.<dts file name> based on the dts specified.
The build process for the kernel searches in the arch/microblaze/boot/dts directory for a specified device tree file and then builds the device tree into the kernel image.
The following command shows the general format for the build target name. Note that the <dts file name> does not include the file extension ".dts".
bash> make ARCH=microblaze simpleImage.<dts file name>
To build a kernel for the provided ML507 reference design, using the following command.
bash> make ARCH=microblaze simpleImage.ml507_mb_v1
To build a clean kernel, use the folllowing command.
bash> make ARCH=microblaze clean
If the Powerpc kernel has been built in the tree, the following command should be ran before building the MicroBlaze Linux kernel to get the links setup in the kernel tree for Microblaze. Remember this wipes out any kernel configuration.
bash> make ARCH=microblaze mrproper
Loading The Kernel Using A Xilinx Probe
In XMD, the following commands can be used to load and run the kernel.
xmd> connect mb mdm xmd> dow arch/microblaze/boot/simpleImage.ml507_mb_v1 xmd> run
The kernel should start booting in less than 20 seconds showing the console output.
Since UartLite is used many times with Microblaze, the console baud rate varies depending on the hardware system build. The baud rate in the device tree file and the command line don't really control it in the case of UartLite. The kernel defaults to 9600 baud rate for the console when using the 16550 UART. The ML507 reference design for this page uses the 16550 and defaults to 9600 baud.
Kernel Boot Args/Command Line
The kernel command line can be pulled from the device tree or setup to use a default command line from the kernel configuration. The default kernel configuration file for Xilinx, xilinx_mmu_defconfig, doesn't use a default kernel command line such that the command line from the device tree is used.
Initramfs Root File System
The kernel allows you to point to a directory containing the root file system it and this is not unique to Microblaze. If you're using a directory and letting the kernel build process build the cpio archive, there MUST be a link in the root of the file system, named init, that points to the initialization binary.
For busybox, create a link named init in the root directory of the filesystem to /bin/busybox. Without this link, you get an error that isn’t real useful as shown below.
VFS: Cannot open root device "<NULL>" or unknown-block(0,0)
Please append a correct "root=" boot option; here are the available partitions:
Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)
The SP605 reference system, referenced above, with checksum offload enabled on the LL TEMAC and with the kernel coniguration tuned as described below, can be expected to get around 20 Mbit in one direction and 40 Mbit in the other using Iperf (TCP). These numbers are from the 2.6.35 kernel and are only intended give an idea of the expected performance.
To get the best network performance, the LL TEMAC core should be used with DMA and it should have receive and transmit checksum offload turned on in the hardware. The SP605 reference design does not have checksum offload turned on such that it won't get the best network performance.
The barrel shifter makes significant performance differences and must be turned on in the hardware and in the kernel configuration. The barrel shifter also allows optimized lib function to be turned on in the kernel configuration as shown in the Kernel Configuration Details section above.
Kernel debug and Tracers should be turned off in the kernel configuration (Kernel Hacking) to get the best network performance.
Ways To Make The Kernel Not Boot
The kernel configuration has an option to allow the default command line to specified in the kernel configuration. When this option is used it prevents the kernel command line from being used in device tree. If you have the console device right in the device tree but wrong in the kernel configuration, then you might not see any console output.
Kernel Linker Address
The address of the memory is contained in the kernel configuration also such that if it's wrong, the kernel won't be linked at the correct address. See the kernel configuration section above for more details.
Bad Kernel Configuration Without All CPU Features
It's not completely clear yet, but it appears that lack of a barrel shifter may cause the kernel not to boot when the following items are selected in the kernel configuration.
The mmu_defconfig in the kernel tree uses these items. The kernel will spew a lot of call traces to the console that aren't much help.
No Console Driver
The mmu_defconfig that is in the kernel tree does not have the UART 16550 items turned on. The xilinx_mmu_defconfig does have them turned on.
No DTS In Raw Linux
When using the "linux.bin" to load the kernel, it seems that the DTS file is not compiled to DTB. When "linux.bin" is linked, the DTB is missing and when executing the kernel it seems to hang (no output). To check if this might be an issue for you, check the "arch/microblaze/boot" directory for a file with "dtb" extension. If you see your "linux.bin" but no "dtb" file, it is likely the build is incomplete.
To solve, first build the simple image (which depend on the dtb and as such will generate it) and then the raw linux binary like this:
make clean make simpleImage.xilinx linux.bin