[microblaze-uclinux] Getting started with uClinux on Microblaze

[John Williams <jwilliams@itee.uq.edu.au>]

Hi folks,

I have just submitted a couple of files to the uClinux maintainers, and 
when they are up you will be able to download the source and give it a go.

The files will be located at

http://www.uclinux.org/pub/uClinux/ports/microblaze/

Attached is the README that describes the process to build and download 
a uClinux kernel to the Microblaze.

This is the first time anyone other than me has attempted to perform 
this process. I've tested my instructions, and I think they are correct. 
  I've also tried not make any assumptions specific to my local build 
environment. However, mistakes happen, so please be patient and give me 
feedback so I can smooth everything out.

Regards,

John
UCLINUX ON MICROBLAZE

(C) 2003 John Williams
This document is released under the GNU GPL.

No warrenty is offered or implied.  If you blow up your hardware, it's not my fault.


The purpose of this document is to provide enough information to allow a moderately 
experienced Microblaze developer/tinkerer to build, download and execute the 
Microblaze port of the uClinux kernel.

The Microblaze port is far from complete, with several outstanding issues before it 
can even be considered to be functional.  Contributions are welcome.

DEVELOPMENT ENVIRONMENT
The first step is to obtain a working development environment and toolchain.

CYGWIN VS XYGWIN
Xilinx ships its EDK gnu tools (such as mb-gcc, mb-ld etc) running under their own 
shell, called Xygwin.  This is built directly from the "standard" linux-like shell known 
as Cygwin.

Unfortunately, as of the time of writing, Xygwin cannot support the uclinux kernel 
configuration and build tools.  Thus, you must do a bit of hacking.

Note for disgruntled Linux users, the EDK and Xilinx synthesis stuff is not supported 
native under Linux.  As soon as it is, I will abandon this Cygwin nonsense and go 
native.  Until then, we're stuck.  Anyone getting the Microblaze gnu-tools working 
under Linux will be hailed as heroes.

Make sure Xilinx EDK is installed first, preferable in c:/EDK or somewhere similar.  
The following instructions assume C:/EDK.

First, go to www.cygwin.org and download and install a good, fresh copy of Cygwin.  
You don't need everything, just the basic shell, the development tools (gcc, binutils, 
cvs etc) and any other stuff you like (don't forget an editor, vi or emacs).  Make sure 
you get the "patch" utility as well.  Install this in C:/cygwin

All kernel development and compilation will now happen under Cygwin.  Forget 
about Xygwin, you'll never use it again (and the next step will make that physically 
impossible!)

TOOLCHAIN
You need a decent binary editor.  I can recommend HexEdit.  The following stage is a 
pain, but you only have to do it once.  

In your hex editor, open up all the .exe and .dll files in the C:/EDK/gnu/Microblaze 
and c:/EDK/bin/nt subtrees.  You then need to go through and replace all instances of 
the string xygwin1.dll with cygwin1.dll.  This is why you need a decent hex editor.  
I'm trying to convince Xilinx to distribute native (ie i386) gcc and binutils in a future 
release of EDK, which will make this hacking unnecessary.

Test out your hacked toolchain by starting a Cygwin shell, create a simple hello.c, 
and run 

       $ mb-gcc -c hello.c

If you don't see any errors, then you're in business.

HARDWARE PLATFORM
In this initial stage, the uClinux kernel is only configured to support one hardware 
target, called mbvanilla.  The use of a static hardware target for reconfigurable 
computing may seem a little strange, but it was vital in nailing down the core issues of 
the Microblaze port.

To get started quickly, you need to make this mbvanilla hardware platform and get it 
into your Xilinx board.  I am using the Insight/Memec P160 prototyping board.  You 
will need to do some work to get it up and running on a different board.  It shouldn't 
be too much work, so if you want to do this just get on the mailing list and I'll help 
you work it out.

Ultimately, we want a way to integrate the kernel configuration with the XPS 
hardware configuration.  I haven't had time to think a lot about this yet, so if you have 
any ideas then let me know.

MBVANILLA
The design files for mbvanilla are located in the directory 
/vendors/Insight/XCV21K_microblaze/hardware.  Copy them out of there and make a 
new Microblaze project with them.

If you can't figure out what to do with the files in that directory, you probably need to 
get a bit more familiar with the Microblaze before you attempt the uClinux stuff.

BUILDING THE KERNEL

1.	Login to the uClinux anonymous CVS server

$ cvs -d:pserver:anonymous@cvs.uclinux.org:/var/cvs login

Press enter when prompted for a password

2.	Decide where you want the uClinux distribution tree to live, say /opt

$ cd /opt

3.	Get the uClinux distribution environment

$ cvs -z3 -d:pserver:anonymous@cvs.uclinux.org:/var/cvs co uClinux-dist

4.	Get the uClinux-2.4.x source, and place it in the uClinux-dist directory

$ cd /opt/uClinux-dist
$ cvs -z3 -d:pserver:anonymous@cvs.uclinux.org:/var/cvs co uClinux-2.4.x

5.	Download microblaze-uclinux-2.4.x-patch, Microblaze-uclinux-2.4.x.tar.gz 
and "kmake" from here:

http://www.uclinux.org/pub/uClinux/ports/microblaze/

6.	Apply the patches

$ cd /opt/uClinux-dist
$ patch -s -p0 < microblaze-uclinux-2.4.x-patch
$ gunzip -c microblaze-uclinux.tar.gz | tar xv 

There should be no complaints or warnings

7.	Make a symbolic link mapping uClinux-2.4.x as linux-2.4.x

$ ln -s uClinux-2.4.x linux-2.4.x

8.	Put kmake somewhere in your Cygwin path (/usr/bin is fine)

9.	Launch the kernel configuration process

$ make menuconfig

The first time you run this it may take some time to build the kernel configuration 
tools etc.

10.	Choose "Target Platform Selection", and make the following selections:

(Insight/XC2V1K_Microblaze)		Vendor/Product
(uClibc)				LibC version
[*] 					Default all settings

Exit, Exit, Yes

Press enter as required for the defaults

$ kmake dep

This may take some time.  It should not report any errors.


11.	You are now ready to build the kernel image:

$ kmake linux

Again, this may take some time, depending on the speed of your build system.

If all goes well, you should end up with a file called "linux" sitting in the uClinux-
2.4.x directory.  Congratulations, you just built a uClinux kernel image for Microblaze!  

This file can now be loaded in to the Microblaze as follows:

12.	Build the mbvanilla hardware and download the mbvanilla bitstream 
	to the Microblaze

13.	Launch xmd, connect to the xmdstub, and download the kernel image

$ linux-2.4.x
$ xmd
Attaching 8e0000
Xilinx Microprocessor Debug (XMD) Engine
Xilinx EDK 3.1.2 Build EDK_C.18
Copyright (c) 1995-2002 Xilinx, Inc.  All rights reserved.

XMD% mbconnect stub -comm serial -port com1 -baud 115200

Connecting to XMD stub..
XMD communication stub initialized. Version No: 2
Communicating with XMD stub on target board
Connected to MicroBlaze "stub" target. id = 0
Starting GDB server for "stub" target (id = 0) at TCP port no 1234
0

XMD% dow linux

14.	Get a windows terminal program (I use Tera Term) listening on com2 at 
57600 baud

15.	Go!

XMD% con

16.	You should see the kernel boot on your terminal screen.  It will eventually 
hang when it runs out of steam (needs a root filesystem yet), but there it is.

It should look a little something like this:

Linux version 2.4.20-uc0 (jwilliams@G435-8350) (gcc version 2.95.3-4 
Xilinx EDK
3.1.2 Build EDK_C.17) #1 Thu Apr 3 11:52:12 EAST 2003
On node 0 totalpages: 256
zone(0): 256 pages.
zone(1): 0 pages.
zone(2): 0 pages.
CPU: XILINX MICROBLAZE
Console: static memory buffer (memcons)
Kernel command line:
Calibrating delay loop... 1.84 BogoMIPS
Memory: 412K/1024K available (430K kernel code, 136K data)
Dentry cache hash table entries: 512 (order: 0, 4096 bytes)
Inode cache hash table entries: 512 (order: 0, 4096 bytes)
Mount-cache hash table entries: 512 (order: 0, 4096 bytes)
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
Page-cache hash table entries: 1024 (order: 0, 4096 bytes)
POSIX conformance testing by UNIFIX
idle schedule
Linux NET4.0 for Linux 2.4
Based upon Swansea University Computer Society NET3.039
Starting kswapd
Blkmem copyright 1998,1999 D. Jeff Dionne
Blkmem copyright 1998 Kenneth Albanowski
Blkmem 1 disk images:
0: FFE9F000-FFE9EFFF [VIRTUAL FFE9F000-FFE9EFFF] (RO)
blk: queue ffe74bec, I/O limit 0Mb (mask 0x0)
Blkmem: bad access: block=0, count=2 (pos=400, len=0)
end_request: I/O error, dev 1f:00 (Blkmem), sector 0
romfs: unable to read superblock
Kernel panic: VFS: Unable to mount root fs on 1f:00

There's a mysterious bug lurking somewhere (I suspect in the irq entry/exit code) that 
sometimes causes the kernel to hang sooner than this, and you sometimes get BUG() 
messages when allocating memory caches.  At this time I have no better advice than 
to power down and upload the kernel again (or get in there and find that bug!).