========================================================= Getting started with Genode on MicroBlaze based platforms ========================================================= Martin Stein This file describes in a practical manner how to work with Genode on platforms which are based on the Xilinx MicroBlaze. It approaches the following aspects: * Build Genode with an existing static scenario of programs which are interacting on with each other and printing information about it to the serial port. * Run this Genode scenario on Qemu and on the Xilinx Spartan 3A Starter Kit * Implement basic support aspects for new MicroBlaze-based platforms If you're not familar with the Genode OS framework, you can read the online documentation: [http://genode.org/documentation/] If you need further information about the Xilinx MicroBlaze, you can read an introduction written by the Genode developers inside your Genode directory: 'base-mb/doc/microblaze.txt' It also covers general issues and limitations respecting the status quo of the Genode porting for MicroBlaze-based platforms. To go in detail about the Xilinx MicroBlaze, you may refer to the Xilinx documentation: [http://www.xilinx.com/tools/microblaze.htm] Prerequisites ============= The MicroBlaze tool chain ~~~~~~~~~~~~~~~~~~~~~~~~~ To build Genode for MicroBlaze, it is recommended to use the following GCC/binutils-compliant tools: * mb-g++ (GCC) 4.1.1 20060524 (Xilinx 11.2 Build EDK_LS2.2 20 Apr 2009 Xilinx 11.2 Build EDK_LS2.2 23 Apr 2009) * GNU ld version 2.16 Xilinx 11.2 Build EDK_LS2.2 23 Apr 2009 * GNU assembler 2.16 Xilinx 11.2 Build EDK_LS2.2 23 Apr 2009 These tools come with the Xilinx Embedded Development Kit (EDK). Expect ~~~~~~ To run the given test scenarios on Genode, you have to install the Tcl-based testing-tool Expect, for example using 'apt-get' on Debian-based Linux distributions: ! sudo apt-get install expect Qemu ~~~~ To run Genode's MicroBlaze port on Qemu, the following Qemu-version is recommended: QEMU emulator version 0.14.50, Copyright (c) 2003-2008 Fabrice Bellard You can get the source code of the latest version via GIT as follows: ! git clone git://git.qemu.org/qemu.git For the scenarios described in here, you have to compile qemu via: ! configure --target-list=microblaze-softmmu ! make Hardware ~~~~~~~~ The tutorial that runs Genode on hardware uses the Xilinx Spartan 3A Starter Kit Revision D board with the FPGA 'xc3s700a', package 'fg484' on speed grade '-4'. It has to be connected to your machine via USB and a serial port RS-232. Tutorial: Build and run Genode's MicroBlaze port ================================================ Initially go to your Genode directory and ensure that the value of the 'QEMU' variable within 'tool/builddir/etc/build.conf.mb-s3a_starter_kit' conforms to the path of your 'qemu-system-microblaze' command. Now build a build directory with the following shell commands: ! ./tool/create_builddir mb-s3a_starter_kit \ ! BUILD_DIR=build.mb-s3a_starter_kit \ On Qemu ~~~~~~~ Change to '/build.mb-s3a_starter_kit'. In this directory, build and run the Genode scenario 'nested_init' for Qemu as follows: ! make run/nested_init This instructs the Genode build system to act according to the run-script '/base-mb/run/nested_init.run'. This script initiates the build of the Genode's core, the program 'init', and a configuration that describes the scenario init start. Then it constructs a bootable image of these 3 files and finally starts Qemu to boot the image virtually. Genode then starts 2 nested 'init' programs, each 'init' instance prints some information about its capabilities. On Hardware ~~~~~~~~~~~ Ensure that the Xilinx Spartan 3A Starter Kit jumpers are set as described for the board-intern demo. Connect the board via USB to your machine and turn it on. Wait till the LED next to the USB connector on board lights up, then list all connected USB devices: ! lsusb This should print, among others, one line like this 'Bus XXX Device XXX: ID XXXX:0008 Xilinx, Inc.' (any X is a wildcard for a number 0-9). Now connect the Serial port that is labeled on board with 'J27' with your computer, this allows us to track debugging output from Genode later. Go to '/build.mb-s3a_starter_kit'. First we have to configure the Spartan 3A with an appropriate MicroBlaze SoC as follows: ! make -C ../base-mb/platform/mb-s3a_starter_kit If it has finished successfully, we can build and run the 'nested_init' scenario by typing the following command from within the build directory: ! RUN_OPT="--target jtag" make run/nested_init After this, the build chain leaves an XMD command prompt to you, which is connected to the SoC on the FPGA via JTAG, so you can steer it as you wish. Genode isn't started already, you can now run a program like 'gtkterm' which intercepts the serial port that Genode will print to. The parameters of the serial port according to 'gtkterm' are: * Speed = 9600 * Parity = none * Bits = 8 * Stopbits = 1 * Flowcontrol = none To start the execution of the 'nested_init' scenario type ! run to the open XMD prompt. The serial port interception should show output similar to that of the Qemu-run. You should avoid uploading multiple times to a once configured platform, it can lead to memory inconsistency. In contrast when configuring the FPGA in between the RAM gets reset. Other scenarios ~~~~~~~~~~~~~~~ You can also find a simple hello-world program at 'base-mb/src/test/hello'. An appropriate 'run' script also exists and can be build from within a build directory via: ! RUN_OPT="--target " make run/hello Hints: How to add support for other MicroBlaze-based platforms ============================================================== The steps described in here don't claim to be complete. They solely should cover the basic of aspects to be considered when implementing support for new platforms and reflect main conventions Genode's MicroBlaze port relies to. New MicroBlaze-based platforms have to fulfill several considerations for now to be compliant to the Genode port. The core expects: * A MicroBlaze SoC with software-loaded MMU that has 64 entries, RAM accessibility and no instruction- and data- caches * The RAM address space to be mapped to 0x90000000 * The CPUs IRQ controller to be an XPS interrupt controller, mapped to 0x81800000 * An XPS Timer mapped to 0x83c00000 with IRQ 0 * An XPS UART Lite mapped to 0x84000000 Basics ~~~~~~ Add a file 'base-mb/mk/spec-.mk' with the content ! SPECS += ! STARTUP_LIB ?= startup ! PRG_LIBS += $(STARTUP_LIB) This file contains aspects to be integrated if 'PLATFORM' occurs in the make-variable 'SPECS' during the build process. It also can add 'SPECS' by itself to provide further details to the build system. For example, the word-width of the CPU like '32bit'. Any other program or library can depend on 'PLATFORM' later by adding it to its 'SPECS'. The second and third lines specify a library that all userland-programs on Genode use to start on 'PLATFORM'. The denoted one is the default '/base-mb/lib/mk/startup.mk' used by the currently supported platforms. You can influence the build-process for 'PLATFORM' furthermore by adding additional lines to this file, for according documentation please refer to: [http://genode.org/documentation/] FPGA Configuration and support by the tool 'run' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To automate testing via the 'run' tool, you have to create a Makefile '/base-mb/platform//Makefile' that provides a target 'upload'. This target should upload an ELF-image, whose absolute path is given by the make argument 'IMAGE', to the according hardware. The above mentioned Makefile should also provide by convention a target 'configure' which prepares the according hardware for the upload of boot images. Typically it configures the FPGA with an appropriate SoC. Therefore, whose source should also be located within '/base-mb/platform//'. Finally you have to edit '/base-mb/run/env' to hint 'run' to your platform. Add inside the function definition 'proc hardware { } {' an additional: ! if { [have_spec {}] } { ! set _hardware ! return $_hardware ! } 'run' then calls 'upload' on '/base-mb/platform//Makefile' and gives the boot image when 'run_genode_until' is called by the according 'run'-script. But first you should create an according build directory as described next. Support for the tool 'create_builddir' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add a file 'tool/builddir/etc/build.conf.' with at least the content ! REPOSITORIES = base-mb ! QEMU = Where 'QEMU' denotes your Qemu command to emulate 'PLATFORM' for Genode Now add a make-target '::' to 'tool/create_builddir' that should describe additional things to do for your build directory. A good point to start is to overwrite the default specifications the build process should take into account when selecting and build targets and libraries. ! @echo "SPECS = genode " > $(BUILD_DIR)/etc/specs.conf This adds the specifics for basic Genode settings, libraries and programs as well as to the contents of your previously created 'base-mb/mk/spec-.mk'.