genode/base-mb/doc/getting_started.txt

        =========================================================
        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 '<GENODE_DIR>/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
'<GENODE_DIR>/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 '<GENODE_DIR>/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 <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-<PLATFORM>.mk' with the content

! SPECS += <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 '<GENODE_DIR>/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
'<GENODE_DIR>/base-mb/platform/<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
'<GENODE_DIR>/base-mb/platform/<PLATFORM>/'.

Finally you have to edit '<GENODE_DIR>/base-mb/run/env' to hint 'run' to
your platform. Add inside the function definition 'proc hardware { } {'
an additional:

! if { [have_spec {<PLATFORM>}] } {
!     set _hardware <PLATFORM>
!     return $_hardware
! }

'run' then calls 'upload' on '<GENODE_DIR>/base-mb/platform/<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.<PLATFORM>' with at least the content

! REPOSITORIES  = base-mb
! QEMU          = <QEMU>

Where 'QEMU' denotes your Qemu command to emulate 'PLATFORM' for Genode
Now add a make-target '<PLATFORM>::' 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 <PLATFORM>" > $(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-<PLATFORM>.mk'.