docs/stepbystep/zynq_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      * minicom
  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 Zedboard Rev. C and D are supported
  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   - U-Boot: http://github.com/Xilinx/u-boot-xlnx
  49     tag: xilinx-v14.7
  50
  51   - Busybox: http://git.busybox.net/busybox
  52     tag: 1_21_1
  53
  54
  55 1. Introduction
  56
  57 The sort demo is an example application to demonstrate ReconOS and its
  58 concepts. It uses both hardware and software threads to sort a bunch of
  59 data by using mboxes to synchronize the different threads and the memory
  60 subsystem of ReconOS to access the data.
  61 You can use ReconOS under different operating systems and on different
  62 FPGAs but this guide only covers the Xilinx Zynq platform running the
  63 Linux operating system.
  64
  65
  66 2. Setup ReconOS
  67
  68 As a first step you should inform you about the general ideas behind
  69 ReconOS and its architecture.
  70
  71 At first you should think about a directory structure you want to use.
  72 As starting point you can use the following one:
  73
  74   $HOME/reconos = $WD
  75     \- reconos     -> the ReconOS repository = $RECONOS
  76     \- linux-xlnx  -> the Linux kernel sources
  77     \- u-boot-xlnx -> the U-Boot sources
  78     \- busybox     -> the busybox sources
  79     \- nfs         -> the root filesystem
  80
  81 This guide assumes this structure, so be aware if you change it.
  82
  83
  84 2.1 Setup the ReconOS toolchain
  85
  86 At first we need to checkout the ReconOS repository:
  87
  88   > cd $WD
  89   > git clone https://github.com/ReconOS/reconos.git
  90
  91 To use the ReconOS toolchain you must configure it to your needs. Therefore,
  92 open $WD/reconos/tools/environment/zynq_linux.sh and adjust it to your machine:
  93
  94   xil_tools:    enter the path to your Xilinx tools
  95                 for example /opt/Xilinx/14.7
  96   gnutool:      enter the path to the gnutoolchain you want to use
  97                 for example /opt/Xilinx/14.7/ISE_DS/EDK/gnu/arm/lin/bin/arm-xilinx-linux-gnueabi-
  98   reconos_arch: no need to change this for this guide
  99   reconos_os:   no need to change this for this guide
 100   reconos_mmu:  no need to change this for this guide
 101
 102   KDIR:  enter the path to the linux kernel
 103          in this case: $HOME/reconos/linux-xlnx
 104   PATH:  enter directories you want to include to the PATH variable
 105          in this case the path to the mkimage utility:
 106          in this case: $HOME/reconos/u-boot-xlnx/tools:$PATH
 107
 108 After setting up you can simply source the main setup script by
 109
 110  > source $WD/reconos/tools/environment/setup_reconos_toolchain.sh zynq_linux
 111
 112 If you do not specify a configuration the default configuration
 113 tools/environment/default.sh is used which should be a link to the
 114 linux_zynq.sh configuration file. To change this, perform the following steps:
 115
 116  > cd $WD/reconos/tools/environment
 117  > ln -sf zynq_linux.sh default.sh
 118
 119 Now you can compile applications to run on the ARM processor included in
 120 the Xilinx Zynq SoC, use the Xilinx tools and use the ReconOS scripts.
 121
 122
 123 3. Setup Linux
 124
 125 3.1 Compile U-Boot
 126
 127 To boot and compile Linux you first have to compile U-Boot:
 128
 129   1. Download the U-Boot sources and change into this direcory
 130      > cd $WD
 131      > git clone https://github.com/Xilinx/u-boot-xlnx.git
 132      > cd u-boot-xlnx
 133
 134   2. Configure the boot mode to download the kernel image via jtag
 135        - Open $WD/u-boot-xlnx/include/configs/zynq_common.h
 136        - Adjust the jtagboot commant by replacing
 137           "jtagboot=echo TFTPing Linux to RAM... && " \
 138           "tftp 0x3000000 ${kernel_image} && " \
 139           "tftp 0x2A00000 ${devicetree_image} && " \
 140           "tftp 0x2000000 ${ramdisk_image} && " \
 141           "bootm 0x3000000 0x2000000 0x2A00000\0"
 142          by
 143           "jtagboot=echo Booting Linux from RAM... && " \
 144           "bootm 0x3000000 - 0x2A00000\0"
 145
 146   3. Disable features disabled in reference designs
 147        - Open $WD/u-boot-xlnx/include/configs/zynq_zed.h
 148        - Disable unsupported features by deleting or commenting out
 149           #define CONFIG_ZYNQ_QSPI
 150           #define CONFIG_ZYNQ_BOOT_FREEBSD
 151
 152   4. Compile U-Boot
 153      > make zynq_zed
 154
 155 3.2 Compile Linux
 156
 157   1. Download the Linux sources and change into this directory
 158      > cd $WD
 159      > git clone https://github.com/Xilinx/linux-xlnx.git
 160      > cd linux-xlnx
 161
 162   3. Configure Linux by using the default configuration
 163      If you whish you can adjust the configuration to your needs
 164      > make xilinx_zynq_defconfig
 165
 166   4. Compile Linux
 167      > make -j8 uImage LOADADDR=0x00008000
 168
 169 3.3 Build the root filesystem
 170
 171 To run Linux we need a root filesystem to mount. In this section we
 172 will build a minimal root filesystem by compiling busybox. If you
 173 do not want to build the root filesystem by your own just download
 174 it from the ReconOS homepage and extract it to $WD/nfs
 175
 176   1. Download busybox
 177      > cd $WD
 178      > git clone git://git.busybox.net/busybox
 179      > cd busybox
 180
 181   2. Configure and build busybox
 182      To create a minimal busybox setup we use the provided default
 183      configuration in the stepbystep folder.
 184      > cp $WD/reconos/docs/busybox_config_1_21_1.config .config
 185      > make -j3
 186      > make install
 187
 188   3. Copy busybox to your root filesystem
 189      > mkdir $WD/nfs
 190      > cp -r _install/* $WD/nfs
 191
 192   4. Create directories
 193      > mkdir dev etc etc/init.d lib mnt opt opt/reconos proc root sys tmp
 194
 195   5. Create inittab
 196      Create $WD/nfs/etc/inittab with the following content:
 197
 198      >=== $WD/nfs/etc/inittab ===>
 199      ::sysinit:/etc/init.d/rcS
 200
 201      # /bin/sh
 202      #
 203      # Start an askfirst shell on the serial ports
 204
 205      ttyPS0::respawn:-/bin/sh
 206
 207      # What to do when restarting the init process
 208
 209      ::restart:/sbin/init
 210
 211      # What to do before rebooting
 212
 213      ::shutdown:/bin/umount -a -r
 214      >=== $WD/nfs/etc/inittab ===>
 215
 216   6. Create rcS
 217      Create $WD/nfs/etc/init.d/rcS with the following content and
 218      make it executable by
 219      > chmod +x $WD/nfs/etc/init.d/rcS
 220
 221      >=== $WD/nfs/etc/init.d/rcS ===>
 222      #!/bin/sh
 223
 224      echo "Starting rcS..."
 225
 226      echo "++ Mounting filesystem"
 227      mount -t proc none /proc
 228      mount -t sysfs none /sys
 229      mount -t devtmpfs none /dev
 230
 231      ttydev=`cat /sys/class/tty/ttyPS0/dev`
 232      ttymajor=${ttydev%%:*}
 233      ttyminor=${ttydev##*:}
 234      if [ -c /dev/ttyPS0 ]
 235      then
 236              rm /dev/ttyPS0
 237      fi
 238
 239      mknod /dev/ttyPS0 c $ttymajor $ttyminor
 240
 241      echo "rcS Complete"
 242      >=== $WD/nfs/etc/init.d/rcS ===>
 243
 244
 245 3.3 Setup NFS
 246
 247 For the development it has proved advantegeous to mount the root filesystem
 248 via NFS.
 249 WARNING: If you develop with other people on the same network make
 250          shure that you do not use the same ip.
 251
 252   1. Configure NFS
 253      Add the following line to your NFS config under /etc/exports
 254      $HOME/reconos/nfs 192.168.42.2(rw,no_root_squash,no_subtree_check)
 255
 256   2. Create virutal network interface to communicate with your board
 257      > sudo ifconfig eth0:1 192.168.42.1 up
 258      You need to restart the NFS server after this
 259
 260
 261 4. Compile ReconOS kernel module and setup ReconOS files
 262
 263 ReconOS combines all drivers needed in a single kernel module which needs
 264 to be compiled and copied together with a initialization script to the
 265 root filesystem.
 266
 267   1. Compile ReconOS module
 268      > cd $RECONOS/linux/driver
 269      > make
 270
 271   2. Copy ReconOS module and initialization script
 272      > mkdir -p $WD/nfs/opt/reconos
 273      > cp $RECONOS/linux/driver/mreconos.ko $WD/nfs/opt/reconos
 274      > cp $RECONOS/linux/scripts/reconos_init.sh $WD/nfs/opt/reconos
 275      > chmod +x $WD/nfs/opt/reconos/reconos_init.sh
 276
 277 You can then simply initialize the entire ReconOS system by executing
 278 reconos_init.sh on the ARM processor.
 279
 280
 281 5. Compile ReconOS library
 282
 283 To compile your applications ReconOS provides all functions in a C library
 284 which must be created.
 285
 286   1. Compile ReconOS library
 287      > cd $RECONOS/linux/lib
 288      > make
 289
 290
 291 6. Compiling the sort demo
 292
 293   1. Adjust the setup config to your working environment
 294        - Open $RECONOS/demos/sort_demo/hw/setup_zynq
 295        - Replace
 296            base_design=zedboard_c_minimal_14.6
 297          by changing the board revision and tool version
 298
 299   2. Create the hardware design by using the setup script
 300      > cd $RECONOS/demos/sort_demo/hw
 301      > reconos_setup.sh setup_zynq
 302
 303   3. Build project
 304      > cd edk_zynq_linux
 305      > xps -nw system
 306      xps> run hwclean
 307      xps> run bits
 308      xps> exit
 309
 310   4. Adjust the device tree to your environment
 311        - Open $RECONOS/demos/sort_demo/hw/edk_zynq_linux/device_tree.dts
 312        - Change
 313            bootargs = "console=ttyPS0,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";
 314          by replacing /nfs/zynqn by /home/<your username>/reconos/nfs (the path to your nfs share) and eventually the ip addresses
 315
 316   5. Compile the device tree for this design
 317      > $WD/linux-xlnx/scripts/dtc/dts -I dts -O dtb -o device_tree.dtb device_tree.dts
 318
 319   6. Compile application and copy it to NFS share
 320      > cd $RECONOS/demos/sort_demo/linux
 321      > make
 322      > cp sort_demo $WD/nfs/opt/reconos
 323
 324
 325 7. Running the sort demo
 326
 327   1. Setting up the board
 328      At first you have to setup your Zynq board. Connect JTAG and
 329      UART to your PC and connect both to the same network.
 330      To select the right bootmode (jtagboot) you must set jumpers
 331      MI02 to MI06 to GND.
 332
 333   2. Open Minicom
 334      You need to open minicom to interact with the Zynq
 335      > minicom -D /dev/ttyACM0
 336
 337   3. Boot Linux
 338      To boot Linux on Zynq you can use the user defined script zynq_boot_jtag.sh
 339      > zynq_boot_jtag.sh $WD/linux-xlnx/arch/arm/boot/uImage
 340                          $RECONOS/demos/sort_demo/hw/edk_zynq_linux/device_tree.dtb
 341                          $RECONOS/demos/sort_demo/hw/edk_zynq_linux/ps7_init.tcl
 342                          $WD/u-boot-xlnx/u-boot
 343      This scripts caches the last used files and uses these if you call
 344      zynq_boot_jtag.sh without parameters. So you do not have to specify
 345      all arguments again the next time you use it.
 346
 347   4. Program FPGA
 348      > cd $RECONOS/demos/sort_demo/hw/edk_zynq_linux
 349      > reconos_download_bitstream.sh implementation/system.bit
 350
 351   5. Initialize ReconOS
 352      zynq> cd /opt/reconos
 353      zynq> ./reconos_init.sh
 354
 355   6. Execute sort demo
 356      zynq> cd /opt/reconos
 357      zynq> ./sort_demo
 358      This shows how to use the sort_demo, e.g. you can run it with 4 HWTs and 2 SWTs
 359      on 16 blocks of data by calling
 360      zynq> ./sort_demo 4 2 16
 361