================================
EBV SoCrates Quickstart Software
================================

(Please check ChangeLog for recent changes)

SD card contents
----------------

The SD card contains the following pieces of software:

 - Linux kernel 4.0 from https://github.com/laodzu/linux/tree/ebv-socrates-v4.0

 - Ready to use FPGA bitstreams:

   - socrates1_lab.rbf: SoCrates workshop lab with SysID and PIO for
     SoCrates v1.x
   - socrates2_lab.rbf: SoCrates workshop lab with SysID and PIO for
     SoCrates v2.x
   - socrates_ocl.rbf: Blank OpenCL image required for alcsoc_drv
   - socrates_fb_touch.rbf: Display controller for LNT+IFI Demo setup

 - Debian 8 root file system

   The root file system is a standard (minimal) Debian 8 armv7a-hf
   installation with the following additions:

   - Gator daemon and kernel module for DS5 debugging
   - Workshop examples
   - OpenCL vector_add demo


SD card creation
----------------

This directory contains all files necessary to generate the SD card
used in the EBV SoCrates evaluation kits.  On a GNU/Linux system,
attach an SD card and call the mk-sd-card.sh script to create the
whole image:

[dzu@pet socrates-quickstart]$ ./mk-sd-card.sh
usage: ./mk-sd-card.sh [device]
       device - block device file of sd-card
		(e.g. /dev/sdb or /dev/mmcblk0)
[dzu@pet socrates-quickstart]$ ./mk-sd-card.sh /dev/sdb

Note that for this to work reliably, no partitions of the SD card must
be mounted at that time.  Be especially aware of this if you use
desktop environments like GNOME that auto-mount all media that gets
attached.

The script will re-create a new partition table with two partitions
and populate them:

1 - Preloader image + U-Boot
2 - Ext3 root file system containing kernel, dtb and FPGA images in /boot


Default boot-up
--------------

U-Boot is setup to boot the kernel+dtb from the Linux partition (below
/boot), so insert the SD card and apply power.  The board will come up
with a default IP address of 192.168.42.5.


Boot via tftp and NFS
---------------------

When you have a working tftp/NFS setup on 192.168.42.20, then you can
boot into kernel+dtb from tftp and into the root file system by running

  run net_nfs

Tuning of IP addresses, file names and root path is easily done by
adjusting U-Boot environment variables, i.e. to load "uImage-devel"
once instead of "uImage", one can do

  setenv bootfile uImage-devel
  run net_nfs


Resetting the environment
-------------------------

If there is the need to reset the environment quickly, then one can
use the prepared "adjust-env.scr" U-Boot script:

  ext2load mmc 0:2 0x100000 boot/adjust-env.scr
  source 0x100000
  saveenv


Script helpers in U-Boot
------------------------

The U-Boot environment contains scripting to allow switching easily
between standalone and networked development.  There are two main
entry points for those boot scenarios:

 - "mmc_mmc" load kernel+dtb from boot directory in the second
   partition and sets up Linux command line to mount this partition as
   root file system

 - "net_nfs" loads kernel+dtb via tftp and setup up Linux command line
   to use an NFS root file system


Default DIP Switch Settings
---------------------------

The bootmode is selected by the DIP switches P8 on SoCrates v1 and P18
on SoCrates v2.  The switches are connected like the following:

,-------+-------+-------+-------+-------+-------+-------+-------.
| MSEL0 | MSEL1 | MSEL2 | MSEL3 | MSEL4 | BSEL0 | BSEL1 | BSEL2 |
`---1---+---2---+---3---+---4---+---5---+---6---+---7---+---8---´

Please note that the MSEL pins are connected to pull-ups and the
switches connect them to ground, so the settings are inverse to the
binary values in the documentation.  The BSEL pins are connected to a
pull-down and the switches connect them to VCC so no inversion is
neccessary for these pins.

Both pins are connected to the DIP switch with the least significant
bit rather than the most significant bit, so the order has to be
reversed to yield a regular binary value.

The MSEL settings select the FPGA configuration mode.  For a complete
overview of the supported modes, refer to Cyclpne V documentation.
Loading the FPGA from HPS is only supported in the FPP mode
however. The default setting (FPPx16, compression enabled, no
encryption) for loading the FPGA from the HPS is as follows:

,-----+-----+-----+-----+-----+-----+-----+-----.
| on  | off | off | on  | on  |  X  |  X  |  X  |
`--1--+--2--+--3--+--4--+--5--+--6--+--7--+--8--´

With the caveats mentioned above, this corresponds to MSEL[4..0] =
0b00110.

The possible values for the BSEL settings are as follows:

,-----+-----+-----+-----+-----+-----+-----+-----.
|  X  |  X  |  X  |  X  |  X  | on  | off | off | Boot from FPGA
+-----+-----+-----+-----+-----+-----+-----+-----+
|  X  |  X  |  X  |  X  |  X  | on  | off | on  | Boot from SD/MMC
+-----+-----+-----+-----+-----+-----+-----+-----+
|  X  |  X  |  X  |  X  |  X  | on  | on  | on  | Boot from QSPI
`--1--+--2--+--3--+--4--+--5--+--6--+--7--+--8--´


The default switch settings of the board should be
like the following:

+-----+-----+-----+-----+-----+-----+-----+-----+
| on  | off | off | on  | on  | on  | off | on  |
+--1--+--2--+--3--+--4--+--5--+--6--+--7--+--8--+

Just flip switch 7 to the on position and the board will boot from
QSPI:

+-----+-----+-----+-----+-----+-----+-----+-----+
| on  | off | off | on  | on  | on  | on  | on  |
+--1--+--2--+--3--+--4--+--5--+--6--+--7--+--8--+

Loading the FPGA from U-Boot
----------------------------

The "boot_linux" script checks the contents of the "fpga_image"
variable.  If it is not equal to "none", it is interpreted as a file
name and fetched from the corresponding source, i.e. from mmc or via
tftp.


Dynamic device tree fix-ups
--------------------------

The "boot_linux" script will iterate over the contents of the
"_fdt_fixups" variable and change the "status" attribute to "ok".
This will effectively enable fragments that are disabled per default.
As an example of how to use that, see the OpenCL demo.


OpenCL demo
-----------

Executing "ocl_setup" before running one of the top level boot
commands will setup the environment to load the OpenCL bit stream and
enable the "aclsoc_drv" fragment in the device tree.  Inside Linux
this will trigger loading of the OpenCL kernel module.  With these
easy steps, one can run the provided "vector_add" demo:

Stop U-Boot auto boot and enter the following command

  run ocl_setup mmc_mmc

This loads the FPGA and starts Linux with the aclsoc_drv enabled in
the device tree.  Then log in as root and do

  cd /home/training/opencl
  source init_opencl.sh
  ./run_vector_add.sh


Using DS5 Streamline
--------------------

To use DS5 Streamline, one has to load the gator kernel module and
start the gator daemon.  To do this, log in as root and do

  cd /home/training/gator
  ./gatord &

This will automatically load the kernel module and start the daemon in
the background.  Start up DS5 on the host system and connect it via
Ethernet to SoCrates (default IP is 192.168.42.5).  To drill down also
on the kernel, one needs to add the vmlinux file to the "Program
Images" in DS5.

Rebuilding the kernel
---------------------

The kernel contained in this package was compiled from the
"ebv-socrates-v4.0" branch from this repository:

https://github.com/laodzu/linux.git

The kernel configuration and the device tree are contained in the
repository, so no separate download is necessary for this.

To regenerate do something like the following

  git clone https://github.com/laodzu/linux.git
  cd linux
  git checkout -b ebv-socrates-v4.0 origin/ebv-socrates-v4.0

Now setup your cross compiler - the example uses a Yocto 2.0 tool chain
build previously, but basically any suitable tool chain will do:

  . /opt/poky-lsb/2.0.1/environment-setup-cortexa9hf-vfp-neon-poky-linux-gnueabi

Compiling the kernel using the standard procedure:

  make socrates_defconfig
  make -j4 LOADADDR=0x8000 uImage
  make socfpga_cyclone5_socrates.dtb

Results of this compilation are the kernel "arch/arm/boot/uImage" and
"arch/arm/boot/dts/socfpga_cyclone5_socrates.dtb". Note that the
latter has to be renamed to "socfpga_socrates.dtb" to fit the U-Boot
scripts described previously.

If you want to compile the kernel modules also and install them
e.g. into an NFS root file system "/opt/socfpga/nfs/rootfs-socrates",
you could do the following:

  make modules
  make INSTALL_MOD_PATH=/opt/socfpga/nfs/rootfs-socrates modules_install

Depending on the access rights of the root file system, you may want
to run the latter command with sudo or ensure that you can write to
"lib/modules" in the hierarchy.


Quick reference of top level scripting commands
----------------------------------------------

boot_linux=run fpga_load; run kernel_load setup_cmdline fdt_fixup; bootm ${kernel_addr_r} - ${fdt_addr_r}
fpga_load=if test ${fpga_image} != "none"; then if test ${kernel_src} = "mmc"; then run fpga_load_mmc; else run fpga_load_net; fi; run bridge_enable_handoff; fi
fpga_load_mmc=ext2load mmc 0:${mmcpart} 0x100000 ${bootdir}/${fpga_image}; fpga load 0 0x100000 ${filesize}
fpga_load_net=tftp 0x100000 ${fpga_image}; fpga load 0 0x100000 ${filesize}
kernel_load=if test ${kernel_src} = "mmc"; then run kernel_load_mmc; else run kernel_load_net; fi
kernel_load_mmc=ext2load mmc 0:${mmcpart} ${kernel_addr_r} ${bootdir}/${bootfile}; ext2load mmc 0:${mmcpart} ${fdt_addr_r} ${bootdir}/${fdt_file}
kernel_load_net=tftp ${kernel_addr_r} ${bootfile}; tftp ${fdt_addr_r} ${fdt_file}
mmc_mmc=setenv kernel_src mmc; setenv rootfs_src mmc; run boot_linux
net_mmc=setenv kernel_src net; setenv rootfs_src mmc; run boot_linux
net_nfs=setenv kernel_src net; setenv rootfs_src net; run boot_linux
ocl_setup=setenv fpga_image fpga_ocl.rbf; run ocl_enable_fixup
setup_cmdline=if test ${rootfs_src} = "mmc"; then run mmcargs ; else run nfsargs ; fi; run addcons addip addmisc addmem


Quick reference of internal scripting commands
----------------------------------------------

ocl_enable_fixup=setenv _fdt_fixups ${_fdt_fixups} /soc/aclsoc_drv
addcons=setenv bootargs ${bootargs} console=${console},${baudrate}
addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off
addmisc=setenv bootargs ${bootargs} uio_pdrv_genirq.of_id=generic-uio
addmem=setenv bootargs ${bootargs} mem=${mem}
fb_enable_fixup=setenv _fdt_fixups ${_fdt_fixups} /soc/framebuffer
fb_init=mw 0x3f000000 0 0x5dc00; mw 0xffc25080 0x3fff; mw 0xff200318 0x3f000000; mw 0xff20031c 0
fb_setup=setenv fpga_image fpga_lnt.rbf; run fpga_load fb_init fb_enable_fixup
fdt_enable=echo Enabling ${fdt_node} in devicetree; fdt addr ${fdt_addr_r}; fdt set ${fdt_node} status "okay"
fdt_fixup=for fdt_node in ${_fdt_fixups}; do run fdt_enable ; done
nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
mmcargs=setenv bootargs root=${mmcroot} rw rootwait


Quick reference of scripting variables and their defaults
---------------------------------------------------------

baudrate=115200
bootcmd=run mmc_mmc
bootdelay=10
bootdir=boot
bootfile=uImage
console=ttyS0
ethaddr=00:4E:8B:C3:E5:9B
fdt_addr_r=0xf00000
fdt_file=socfpga_socrates.dtb
fpga_image=none
ipaddr=192.168.42.5
kernel_addr_r=0x10000000
kernel_src=mmc
mem=1024M
mmcpart=2
mmcroot=/dev/mmcblk0p2
netmask=255.255.255.0
rootfs_src=mmc
rootpath=/opt/socfpga/nfs/rootfs-socrates/
serverip=192.168.42.20