docs/stepbystep/microblaze_linux.txt

   1                                                        ____  _____
   2                            ________  _________  ____  / __ \/ ___/
   3                           / ___/ _ \/ ___/ __ \/ __ \/ / / /\__ \
   4                          / /  /  __/ /__/ /_/ / / / / /_/ /___/ /
   5                         /_/   \___/\___/\____/_/ /_/\____//____/
   6
   7 ======================================================================
   8
   9   title:        ReconOS
  10
  11   project:      ReconOS
  12   author:       Christoph Rüthing, University of Paderborn
  13   description:  This is step by step guide introduces the usage of
  14                 ReconOS by setting up the sort demo application.
  15
  16 ======================================================================
  17
  18 0. Prerequisites
  19
  20 This guide assumes that you have basic knowledge of the development
  21 for an FPGA and setup the appropriate tools and your board. The
  22 following list includes all prerequisites:
  23
  24   - Linux workstation with a distribution of your choice including
  25      * picocom
  26      * NFS server
  27
  28   - Xilinx ISE Design Tools (Version 14.6 or 14.7 for this guide)
  29     including the following components
  30      * Xilinx Platform Studio (XPS)
  31      * ARM compiler collection
  32      * Software Development Kit (SDK)
  33      * Xilinx Microprocessor Debugger (XMD)
  34
  35   - Evaluation board connected to your workstation
  36     Currently only the ML605 board is supported out of the box
  37      * JTAG connection to program the FPGA
  38      * UART connection to interact with the board
  39
  40 This guide uses several external sources and downloads them to your
  41 local machine. To make shure that everything works fine you can use
  42 the follwing tested versions or can try it with the newest ones
  43 available:
  44
  45   - Linux Kernel: http://github.com/Xilinx/linux-xlnx
  46     tag: xilinx-v14.7
  47
  48   - Busybox: http://git.busybox.net/busybox
  49     tag: 1_21_1
  50
  51
  52 1. Introduction
  53
  54 The sort demo is an example application to demonstrate ReconOS and its
  55 concepts. It uses both hardware and software threads to sort a bunch of
  56 data by using mboxes to synchronize the different threads and the memory
  57 subsystem of ReconOS to access the data.
  58 You can use ReconOS under different operating systems and on different
  59 FPGAs but this guide only covers the Xilinx ML605 board running the
  60 Linux operating system.
  61
  62
  63 2. Setup ReconOS
  64
  65 As a first step you should inform you about the general ideas behind
  66 ReconOS and its architecture.
  67
  68 At first you should think about a directory structure you want to use.
  69 As starting point you can use the following one:
  70
  71   $HOME/reconos = $WD
  72     \- reconos             -> the ReconOS repository = $RECONOS
  73     \- linux-xlnx          -> the Linux kernel sources
  74     \- busybox             -> the busybox sources
  75     \- nfs                 -> the root filesystem
  76     \- microblaze_v2.0_le  -> gnu tools for microblaze
  77
  78 This guide assumes this structure, so be aware if you change it.
  79
  80 2.1 Download GNU-Toolchain for microblaze
  81
  82 To compile applications for the microblaze processor we need a
  83 compiler toolchain. The microblaze processor lacks a stable
  84 toolchain and therefore we need to use different ones for
  85 different purposes. You can skip this step (2.1) if you do
  86 not want to compile busybox and use the provided root filesystem.
  87
  88   1. Checkout toolchain repository
  89      > cd $WD
  90      > git clone git://git.xilinx.com/xldk/microblaze_v2.0_le.git
  91
  92   2. Extract the toolchain
  93      > cd microblaze_v2.0_le
  94      > tar xfz microblazeel-unknown-linux-gnu.tgz
  95
  96 2.2 Setup the ReconOS toolchain
  97
  98 At first we need to checkout the ReconOS repository:
  99
 100   > cd $WD
 101   > git clone https://github.com/ReconOS/reconos.git
 102
 103 To use the ReconOS toolchain you must configure it to your needs. Therefore,
 104 open $WD/reconos/tools/environment/microblaze_linux.sh and adjust it to
 105 your machine:
 106
 107   xil_tools:    enter the path to your Xilinx tools
 108                 for example /opt/Xilinx/14.7
 109   gnutool:      enter the path to the gnutoolchain you want to use
 110                 in this case /opt/Xilinx/14.7/ISE_DS/EDK/gnu/microblaze/linux_toolchain/lin64_le/bin/microblazeel-xilinx-linux-gnu-
 111   reconos_arch: no need to change this for this guide
 112   reconos_os:   no need to change this for this guide
 113   reconos_mmu:  no need to change this for this guide
 114
 115   KDIR:  enter the path to the linux kernel
 116          in this case: $HOME/reconos/linux-xlnx
 117
 118 After setting up you can simply source the main setup script by
 119
 120  > source $WD/reconos/tools/environment/setup_reconos_toolchain.sh microblaze_linux
 121
 122 If you do not specify a configuration the default configuration
 123 tools/environment/default.sh is used which should be a link to the
 124 linux_zynq.sh configuration file. To change this, perform the following steps:
 125
 126  > cd $WD/reconos/tools/environment
 127  > ln -sf microblaze_linux.sh default.sh
 128
 129 Now you can compile applications to run on the Micorblaze processor, use the
 130 Xilinx tools and use the ReconOS scripts.
 131
 132
 133 3. Setup Linux
 134
 135 3.1 Configure Linux
 136
 137   1. Download the Linux sources and change into this directory
 138      > cd $WD
 139      > git clone https://github.com/Xilinx/linux-xlnx.git
 140      > cd linux-xlnx
 141
 142   3. Configure Linux by using the default configuration
 143      > make mmu_defconfig
 144
 145   4. Adjust configuration to ReconOS
 146      > make menuconfig
 147
 148      Set the following options:
 149        Platform Options -> Targeted FPGA family: virtex6
 150        Platform Options -> Physical address where Linux Kernel is: 0x20000000
 151        Platform Options -> Core version number: 8.50.b
 152        Processor Type and Features -> Commandline:
 153          console=ttyUL1,115200 root=/dev/nfs rw nfsroot=192.168.42.1:/nfs/zynqn,tcp ip=192.168.42.2:::255.255.255.0:reconos:eth0:off earlyprintk
 154          by replacing /nfs/zynqn by /home/<your username>/reconos/nfs (the path to your nfs share) and eventually the ip addresses
 155        Networking support -> Networking options -> IP: kernel level autoconfiguration: yes
 156        File systems -> Network File Systems -> Root file system on NFS: yes
 157        Device Drivers -> Generic Driver Options -> Maintain devtmpfs to mount at /dev: yes
 158
 159      If you whish you can further adjust the configuration to your needs
 160
 161   5. A small Makefile fix
 162      To compile a simpleImage we need to fix the Makefile
 163      $WD/linux-xlnx/arch/microblaze/boot/Makefile by deleting
 164      line 33: $(call if_changed,uimage)
 165
 166   6. Compile Linux
 167      To compile Linux we need the device tree from the hardware project and
 168      therefore compilation is done later but we need to prepare the kernel
 169      to build modules.
 170      > make -j3 linux.bin
 171
 172 3.3 Build the root filesystem
 173
 174 To run Linux we need a root filesystem to mount. In this section we
 175 will build a minimal root filesystem by compiling busybox. If you
 176 do not want to build the root filesystem by your own just download
 177 it from the ReconOS homepage and extract it to $WD/nfs
 178
 179   1. Download busybox
 180      > cd $WD
 181      > git clone git://git.busybox.net/busybox
 182      > cd busybox
 183
 184   2. Change compile collection for busybox
 185      Since the toolchain provided by Xilinx's default installtion
 186      does not work for busybox we need to change the CROSS_COMPILE
 187      environment variable.
 188      > export CROSS_COMPILE_BAK=$CROSS_COMPILE
 189      > export CROSS_COMPILE=$HOME/reconos/microblaze_v2.0_le/microblazeel-unknown-linux-gnu/bin/microblazeel-unknown-linux-gnu-
 190
 191   3. Configure and build busybox
 192      To create a minimal busybox setup we use the provided default
 193      configuration in the stepbystep folder.
 194      > cp $WD/reconos/docs/busybox_config_1_21_1.config .config
 195      > make -j3
 196      > make install
 197
 198   4. Copy busybox to your root filesystem
 199      > mkdir $WD/nfs
 200      > cp -r _install/* $WD/nfs
 201
 202   5. Create directories
 203      > mkdir dev etc etc/init.d lib mnt opt opt/reconos proc root sys tmp
 204
 205   6. Create inittab
 206      Create $WD/nfs/etc/inittab by copying from the stepbystep directory
 207
 208      >=== $WD/nfs/etc/inittab ===>
 209      ::sysinit:/etc/init.d/rcS
 210
 211      # Start an askfirst shell on the serial ports
 212      ttyUL1::respawn:-/bin/sh
 213
 214      # What to do when restarting the init process
 215      ::restart:/sbin/init
 216
 217      # What to do before rebooting
 218      ::shutdown:/bin/umount -a -r
 219      >=== $WD/nfs/etc/inittab ===>
 220
 221   7. Create rcS
 222      Create $WD/nfs/etc/init.d/rcS with the following content and
 223      make it executable by
 224      > chmod +x $WD/nfs/etc/init.d/rcS
 225
 226      >=== $WD/nfs/etc/init.d/rcS ===>
 227      #!/bin/sh
 228
 229      echo "Starting rcS..."
 230
 231      echo "++ Mounting filesystem"
 232      mount -t proc none /proc
 233      mount -t sysfs none /sys
 234      mount -t devtmpfs none /dev
 235
 236      echo "rcS Complete"
 237      >=== $WD/nfs/etc/init.d/rcS ===>
 238
 239   8. Restore CROSS_COMPILE
 240      > export CROSS_COMPILE=$CROSS_COMPILE_BAK
 241      > unset CROSS_COMPILE_BAK
 242
 243
 244 3.3 Setup NFS
 245
 246 For the development it has proved advantegeous to mount the root filesystem
 247 via NFS.
 248 WARNING: If you develop with other people on the same network make
 249          sure that you do not use the same ip.
 250
 251   1. Configure NFS
 252      Add the following line to your NFS config under /etc/exports
 253      $HOME/reconos/nfs 192.168.42.2(rw,no_subtree_check,anonuid=<unixuserid>,anongid=<unixgroupid>)
 254
 255   2. Create virtual network interface to communicate with your board
 256      > sudo ifconfig eth0:1 192.168.42.1 up
 257      You need to restart the NFS server after this
 258
 259
 260 4. Compile ReconOS kernel module and setup ReconOS files
 261
 262 ReconOS combines all drivers needed in a single kernel module which needs
 263 to be compiled and copied together with a initialization script to the
 264 root filesystem.
 265
 266   1. Compile ReconOS module
 267      > cd $RECONOS/linux/driver
 268      > make
 269
 270   2. Copy ReconOS module and initialization script
 271      > mkdir -p $WD/nfs/opt/reconos
 272      > cp $RECONOS/linux/driver/mreconos.ko $WD/nfs/opt/reconos
 273      > cp $RECONOS/linux/scripts/reconos_init.sh $WD/nfs/opt/reconos
 274      > chmod +x $WD/nfs/opt/reconos/reconos_init.sh
 275
 276
 277 5. Compile ReconOS library
 278
 279 To compile your applications ReconOS provides all functions in a C library
 280 which must be created.
 281
 282   1. Compile ReconOS library
 283      > cd $RECONOS/linux/lib
 284      > make
 285
 286
 287 6. Compiling the sort demo
 288
 289   1. Adjust the setup config to your working environment
 290        - Open $RECONOS/demos/sort_demo/hw/setup_microblaze
 291        - Replace
 292            base_design=ml605_minimal_14.6
 293          by changing the tool version
 294
 295   2. Create the hardware design by using the setup script
 296      > cd $RECONOS/demos/sort_demo/hw
 297      > reconos_setup.sh setup_microblaze
 298
 299   3. Build project
 300      > cd edk_microblaze_linux
 301      > xps -nw system
 302      xps> run hwclean
 303      xps> run bits
 304      xps> exit
 305
 306   4. Copy device tree to Linux source tree
 307      > cp device_tree.dts $WD/linux-xlnx/arch/microblaze/boot/dts/reconos.dts
 308
 309   5. Compile Linux with this device tree
 310      > cd $WD/linux-xlnx
 311      > make -j3 simpleImage.reconos
 312
 313   6. Compile application and copy it to NFS share
 314      > cd $RECONOS/demos/sort_demo/linux
 315      > make
 316      > cp sort_demo $WD/nfs/opt/reconos
 317
 318
 319 7. Running the sort demo
 320
 321   1. Setting up the board
 322      At first you have to setup your ML605 board. Connect JTAG and
 323      UART to your PC and connect both to the same network.
 324
 325   2. Program FPGA
 326      > cd $RECONOS/demos/sort_demo/hw/edk_microblaze_linux
 327      > reconos_download_bitstream.sh implementation/system.bit
 328
 329   3. Open Picocom
 330      You need to open minicom to interact with the ML605
 331      > picocom /dev/ttyUSB0 -b115200
 332
 333   4. Boot Linux
 334      > cd $WD/linux-xlnx
 335      > reconos_download_executable.sh arch/microblaze/boot/simpleImage.reconos
 336
 337   5. Initialize ReconOS
 338      mb> cd /opt/reconos
 339      mb> ./reconos_init.sh
 340
 341   6. Execute sort demo
 342      mb> cd /opt/reconos
 343      mb> ./sort_demo
 344      This shows how to use the sort_demo, e.g. you can run it with 4 HWTs and 2 SWTs
 345      on 16 blocks of data by calling
 346      mb> ./sort_demo 4 2 16
 347