Introduction

This tutorial is divided into multiple tracts. There is an advanced tract and a basic tract. This advanced tract requires Altera tools to be downloaded and installed. The basic tract requires only a terminal emulator program and a computer with a USB port.

NOTE:If following the Basic tract, the advanced tract sections can be skipped throughout the exercises.

404 Not Found

Install Tools

• Install terminal emulator application
  • Windows
    • Teraterm: http://ttssh2.sourceforge.jp/
    • Putty: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
  • Linux
    • Red Hat/CentOS/Fedora:
      • Run at the prompt: “sudo yum install putty”
      • Run at the prompt: “sudo yum install minicom”
    • Ubuntu/Debian:
      • Run at the prompt: “sudo apt-get install putty”
      • Run at the prompt: “sudo apt-get install minicom”

Install Advanced Tools

• Install Quartus (Hardware Design Tools):
  • Download Link: http://dl.altera.com/14.1/?edition=web
  • Documentation: http://www.altera.com/literature/lit-qts.jsp
• Install SoC EDS:
  • Download Link: http://dl.altera.com/soceds/?edition=web
  • Documentation: http://www.altera.com/literature/ug/ug_soc_eds.pdf

• Install NIOS IDE (Comes installed by default with Quartus)

Board Setup

For this tutorial the Arrow Cyclone V SoCKit will be used. Please double check that the following switch and jumper settings on your board match the settings in table 1.1:

Board Reference	Signal Name	Setting	Default
J17	BOOTSEL0	Pins 1 and 2 shorted = logic 1 Pins 2 and 3 shorted = logic 0	Pins 1 and 2 shorted
J19	BOOTSEL1	Pins 1 and 2 shorted = logic 1 Pins 2 and 3 shorted = logic 0	Pins 2 and 3 shorted
J18	BOOTSEL2	Pins 1 and 2 shorted = logic 1 Pins 2 and 3 shorted = logic 0	Pins 1 and 2 shorted
J15	CLKSEL0	Pins 1 and 2 shorted = logic 1 Pins 2 and 3 shorted = logic 0	Pins 2 and 3 shorted
J16	CLKSEL0	Pins 1 and 2 shorted = logic 1 Pins 2 and 3 shorted = logic 0	Pins 2 and 3 shorted
SW4.1	JTAG_HSMC_EN	1 = HSMC In JTAG Chain 0 = HSMC bypassed	“0” (HSMC Bypassed)
SW4.2	JTAG_HPS_EN	1 = HPS In JTAG Chain 0 = HPS bypassed	“1” (HPS Enabled)
SW6	MSEL[4:0]	0b0000	0b0000

The BOOTSEL[2:0] = 0b101 settings above will configure the board to boot from a SD/MMC Flash memory device in 3.0V mode.

More information on the Arrow Cyclone V SoCKit Evaluation Board can be found here:

http://rocketboards.org/foswiki/Documentation/ArrowSoCKitEvaluationBoard

Download Tutorial Files

All files associated with this tutorial can be downloaded directly from the Altera Linux Community Portal, RocketBoards.org at the following location:

• http://rocketboards.org/foswiki/Documentation/BuildingMultiProcessorSystems

Included are the lab manual, presentation slides,sdcard image and basic instructions to get started.

Lab 1.a – Basic with Terminal Emulator Only

• Connect USB cable from USB micro connector J4 on the board (labeled “USB to UART”) to computer
  • Serial Connection Settings: 115200 bps, 8-N-1
  • Figure 2 below shows the “USB to UART” Connector on the board. This is the micro-USB connecor closest to the Ethernet connector.

• If not already inserted, please inserted the SD card into the SD/MMC connector underneath the board (under the HKEY_0 and HKEY_1 buttons on the opposite side of the board from the micro-USB connectors).
  • Note: for instructions on downloading and writing the lab SD card image. Please see http://rocketboards.org/foswiki/Documentation/BuildingMultiProcessorSystems
• Press Power Button Switch
  • Note: You should see the U-Boot and Linux Kernel Messages followed by the Linux login Prompt in the terminal emulator window.
• Login to Linux
  • Username: root
  • Password: <None> (I know it is secure! J)
• Note: This loaded a default hardware design (RBF file) and device tree (DTB). We will now change the design.
• Change U-Boot to load a new Hardware Design and Device Tree Blob (To be used in Lab2)
• Cd “/media/fat/lab1”
• Make sure that the “soc_system.dts” device tree source file contains the following ranges property of the “bridge@0xc0000000” node.

0x00000001 0x00030000 0xff230000 0x00000080

• Edit the “soc_system.dts” device tree source file to add the following node under the “bridge@0xc0000000” node:

led_gpio: gpio@0x100030000 {
     compatible = "altr,pio-14.1", "altr,pio-1.0";
     reg = <0x00000001 0x00030000 0x00000010>;
     clocks = <0x2>;
     altr,gpio-bank-width = <6>; 
     resetvalue = <0>;
     #gpio-cells = <2>;
     gpio-controller;
};

• Save the file and run the following command to generate the device tree blob
  • Type “dtc –I dts –O dtb soc_system.dts –o soc_system.dtb
• Edit the “uboot-script.txt” file
  • The vim, vi, emacs, pico and nano editors come pre-installed on the included rootfs.
• Change the hardware design by changing this line:

fatload mmc 0:1 $fpgadata soc_system.rbf;

• To:

fatload mmc 0:1 $fpgadata lab1/soc_system.rbf;

• Change the device tree blob by changing this line:

set fdtimage soc_system.dtb;

• To:

set fdtimage lab1/soc_system.dtb;

• To create the u-boot script with u-boot header:
  • type “mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "U-Boot Script" -d uboot_script.txt ../u-boot.scr”
• Reboot the board by typing the following at the prompt:
  • “reboot”
• Power-cycle the board by pressing the power button twice
  • __Note: You may have to reconnect terminal emulator after the board has been power cycled.__
• Boot Strap NIOS
  • Wait for the login prompt to reappear, and re-log in. (Username: root; no password)
  • At Linux prompt, change directory to the first lab by typing “cd /media/fat/lab1”
  • Ensure that the Altera GPIO kernel module is loaded by typing “modprobe gpio-altera”.
  • To run the lab1 executable, type “load_nios_lab1” at the prompt.
• User to Add: Change Software & Rerun
• Edit the load_nios_lab1.c file
• Uncomment the lines label /* UNCOMMENT ME */
• Save the .c file and recompile by typing “make clean all”
• Rerun by typing “./load_nios_lab1” at the prompt
• Notice the output text and the board LEDs.

We are now ready for Lab 2!

Lab 1 References

More information can be found in the following links:

• http://www.altera.com/literature/hb/nios2/n2sw_nii5v2.pdf
• NIOS Software Build Tools plugin for Eclipse: http://www.altera.com/literature/hb/nios2/n2sw_nii52017.pdf
• http://www.altera.com/devices/processor/arm/cortex-a9/software/proc-soc-embedded-design-suite.html

Lab 2.a – Basic: Mailbox

• At the Linux prompt change into the Lab2 source code directory by typing the following:
  • “cd /media/fat/lab2”
• Ensure that the Altera GPIO kernel module is once again loaded by typing the following:
  • “modprobe gpio-altera”.
• Type “./mbox_lab2” at the prompt
• Note: This will give you an “ARM>” prompt. At this prompt, you can type the following commands:
  • “reset” – this resets the NIOS processor(s)
  • “quit” - this exits the mbox_lab2 program
  • “exit” – this also exits the mbox_lab2 program
  • “nios0” – this enables the NIOS 0 processor to access the ARM UART and gives you a “NIOS>” prompt
• Type “nios0” at the “ARM>” prompt.
• At the “NIOS>” prompt, you can type any of the following commands:
  • “ledoff#” – where # is a number from 0-3. This will turn off LED number 0-3.
  • “ledon#” – where # is a number from 0-3. This will turn on LED number 0-3.
  • “quit” - this releases control of the ARM UART, giving the ARM control
  • “exit” – same as “quit”
• Type “quit” at the “NIOS>” prompt to get back to the “ARM>” prompt”
• Also type “quit” at the “ARM>” prompt to exit the mbox_lab2 program.
• User to Add: Enable second NIOS subsystem
• Note: The NIOS and the ARM communicate via Hardware Mailbox IP and a simple message protocol. For more information, please refer to the lab presentation.
  • Edit the “mbox_lab2.c” file with your choice of editor to add the following lines near line 189 to load the NIOS 1 (second NIOS processor) code:

for(i=0; i < nios1_code_size ;i++)
{
*(load1_address+i) = nios1_code[i];
}

• Edit the “mbox_lab2.c” file to add the following lines near line 229 to enable the “nios1” command in our command processor. You can cut and past the “nio0” section. Be sure to change the initial Grant/Go message from “G00” to “G10” as the second byte denotes to which NIOS processor the message should be sent.

  else if(!strncmp("nios1", cmd_buffer, 5))
  {
    /* Wait for TX Queue to be empty */
    printf(" - Waiting for Message Queue to empty...\n");
    while((*(volatile int*)(mbox1_address+0x2002) & 1) != 0 ) { }
    printf(" - Granting UART Access to NIOS 1.\n");
    printf(" - Waiting for NIOS 1 to Complete...\n");

    /* Send Grant/Go message to NIOS */
    send_message = "G10";
    *(mbox1_address+0x2000) = *(int *)send_message;

    /* Disable ARM/Linux Access to UART (be careful here) */
    config.c_cflag &= ~CREAD;
    tcsetattr(fd, TCSAFLUSH, &config);

    /* Wait for RX Queue to be non-empty (has RX Message) */
    while((*(volatile int*)(mbox1_address+2) & 2) == 0 ) { }

    /* Re-enable ARM/Linux Access to UART */
    config.c_cflag |= CREAD;
    tcsetattr(fd, TCSAFLUSH, &config);

    /* Capture and display RX Message */
    printf("\x1b[23;0H"); /* move to line 24, column 0 */
    printf(" - Message Received. DATA = '%s'.\n",
      (char*)(mbox1_address));
   }

• Exit the text editor, saving your work.
• At the Linux prompt, type “make clean all” to rebuild the lab program.
• Type “./mbox_lab2” at the prompt, to restart the program.
• Note: The “ARM>” prompt now has the “nios1” command.
• Type “nios1” at the “ARM>” prompt
• Note: nios1 has all the same commands as the nios0, with the addition of the “cylon” and “knightrider” commands.
• Type any nios1 or nios0 commands you wish.
• To exit this lab, type “quit” at the “nios#>” prompt, and type “quit” at the “ARM>” prompt”
• You are now ready for Lab 3!

Lab 2 References:

• Altera HPS UART Register Map: http://www.altera.com/literature/hb/cyclone-v/hps.html#topics/sfo1410069884928.html
• Mailbox IP: http://www.altera.com/literature/ug/ug_embedded_ip.pdf
  • Other Soft IP Cores: Interrupt Controller, Timer, System ID, DMA, On-chip memory, PIO, JTAG controller, etc

Lab 3.a – Basic: Mutex and Tetris

• At the Linux prompt change into the Lab3 source code directory by typing the following:
  • “cd /media/fat/lab3/ctris-0.42”
• Note: Notice the extra level of directory hierarchy for this lab.
• Type “./ctris” to bring up the open source CTRIS ncurses program by Dominik Hackl.
• Use these keys to play:
  • “Left arrow” moves left
  • “Right arrow” moves right
  • “Up arrow” to rotate blocks
  • “Down arrow” to drop blocks
  • “q” to quit
  • “p” to pause
• Note: Don’t play too long, we have a lab to do! J
• Exit out of CTRIS by pressing the “q” key several times.
• Also, to release the SoCKit connection, press the “KEY0” and “KEY3” buttons at the same time.
• Back at the Linux prompt,edit the “nios_buttons.c” file to add the following highlighted line near line 116. This will use the Linux mutex lock to lock our critical section of code (code that allows each NIOS to write to a GPIO and the ARM to read the resultant value).

/***********************************************************/
/* Mutex Lock - Critical Section below */
/***********************************************************/
pthread_mutex_lock(&lock);

• Edit the “nios_buttons.c” file to add the following highlighted line near line 168. This will use the Linux mutex lock to unlock our critical section.

/***********************************************************/
/* Mutex Unlock */
/***********************************************************/
pthread_mutex_unlock(&lock);

• Edit the “nios_buttons.c” file to add the following lines near line 223. This will initialize our mutex.

if (pthread_mutex_init(&lock, NULL) != 0)
{

printf("\nERRORMutex Init Failed.\n");
return 1;
}

• Edit the “nios_buttons.c” file to add the following highlighted line near line 253. This will destory our mutex.

printf("Thank You for Playing!\n");
/* Destroy Mutex */
pthread_mutex_destroy(&lock);

• Exit your text editor session, and remake CTRIS by typing the following at the Linux prompt:
  • “make clean all”
• Once again type “./ctris”.
• Now you can use the following keys on the SoCKitboardtoplayCTRIS:
  • “KEY0” move right
  • “KEY3” move left
  • “KEY1” or “KEY2” to rotate blocks

Note: Have fun and keep playing. That is it! Thanks for participating!

Lab 3.b – Advanced: Debugging with Eclipse/DS-5

1. Start an Embedded Command Shell by running /embedded_command_ shell.sh.
2. Start Eclipse by running the eclipse command from the Embedded Command Shell.
3. The Eclipse tool, part of the ARM DS-5 AE, prompts for the workspace folder to be used. Accept the suggested folder and click OK.
4. The ARM DS-5 AE "Welcome" screen appears. It can be used to access documentation, tutorials, and videos.
5. Select Window > Open Perspective > DS-5 Debug to open the Workbench. Alternatively, you can Click on the link Go to the Workbench located under the list of "DS-5 Resources". Debugging the Kernel This section presents how to create a Debug Configuration that is then used to debug the Linux kernel.
6. Select Run > Debug Configurations… to open the Debug Configurations dialog box.
7. In the Debug Configurations dialog box, right-click DS-5 Debugger on the left panel and select New.
8. In the Debug Configurations dialog box, perform the following:

• Rename the configuration to DebugLinux _DevKit using the Name edit box
• Select the Target to be Altera > CycloneVSoC >Linux Kernel and/or Device Driver Debug >Debug CortexA9x2 SMP via Altera USB-Blaster
• Click the Browse button near the Connection edit box and select the desired USB Blaster instance

1. Click on the Debugger and perform the following steps:

• Select option Connect Only for Run Control
• Check Execute debugger commands check box
• Add the debugger commands to stop cores and load image symbols for the Linux executable, as shown in the following figure.
• Add the path to the Linux source files on the host machine to allow the debugger to locate them

1. Click the Debug button. The debugger connects to the board, stops the cores as instructed and loads the kernel symbols. It determines where the cores are stopped, and highlights it in the source code. The following figure shows the debugger stopped in the idle instruction.
2. To view the running threads, maximize the top left panel. It shows Active Threads with the two currently executing threads. Also the All Threads can be expanded to show all threads in the system.
3. Minimize the Debug Control panel and maximize the Functions panel from top right. All of the functions in the kernel are displayed. The Functions panel supports the following operations for each function:

• Run up to the function
• Set PC to function
• Locate in source code, memory, or disassembly
• Set breakpoints to software or hardware
• Set trace points to enable, disable, or toggle

1. Select Modules panel to view the currently loaded modules. In the example below only the ipv6 module is loaded.
2. Add breakpoints at the module load and module unload functions. As modules are loaded with insmod, and removed with rmmod, the DS-5 AE will reflect the changes

Lab 3 References:

• Linux Mutex Examples: http://www.thegeekstuff.com/2012/05/c-mutex-examples/
• http://www.hackl.dhs.org/ctris/
• https://www.altera.com/en_US/pdfs/literature/ug/ug_soc_eds.pdf (Debugging with DS-5 for Eclipse)
• Compiling Preloader, Linux Kernel and Using GIT
  • http://rocketboards.org/foswiki/Documentation/GitGettingSTarted
• Compiling Root File System using Buildroot: http://rocketboards.org/foswiki/Documentation/BuildrootForSoCFPGA