Preparation

0) Writing Assembly Programs

In The Lab

1) Introduction

1a) Table of Contents

2) QuickStart Guide

3) More information on the compiling you just did

While it is possible to program the NIOS-II processor using a language such as C, the creation of an executable file always requires the creation of an assembly language file, as shown in the figure below. This assembly file can be written automatically by the compiler or directly by the programmer. The assembly language gives to the programmer direct access to the hardware (the registers, the memory and the devices attached to the DE2 board). For this reason, the assembly language is a low-level language as opposed to the C language which is a high-level one (since it abstracts the programmer away from the hardware).

So when you typed make SRCS=leds_7segs.s run at the command line, a number of commands were performed for you. The flow of commands is as follows:

As illustrated, there are 3 main steps:

4) More information on the program you just ran

In this section, we examine the difference between the assembly source code and the machine code.

4a) Listing of a program

Take a look at the source code of the program you run in the QuickStart Section by typing less leds_7segs.s (or by opening it in Wordpad). Use the arrows on your keyboard to scroll or q to quit the "less" program. You will obtain an output in the following format:

This program, typed by a human, is meant to be converted to an executable program by the assembler software. The components of a program as shown in the figure above are:

The NIOS-II processor executes instruction one by one in the order specified in the program. The program is a binary file consisting of a list of machine codes representing instructions and some meta-data. The assembler will convert each instruction of the source code into one machine-executable instruction, except for the "movia" opcode, the only pseudo-instruction exception that the assembler converts into 2 machine-executable instructions. Apart from the pseudo-instructions, there is a one-to-one correspondence between the machine code and the source code, so it is possible to revert a machine code into its corresponding assembly code. To inspect the assembly code of the compiled program you ran in the QuickStart Section, type make SRCS=leds_7segs.s disasm in the NIOS-II Command Shell. You should get an output with the following format:

Notice how the value next to the label is the same as the address of the immediately following instruction in the executable. The addresses and machine codes are given in hexadecimal. In the NIOS-II instruction set, all instructions are represented on 32 bits. This explains why addresses of consecutive instructions are separated by a distance of 4 bytes (32 bits). Compare this output with the original source program. Observe how the "movia" opcode is converted into a "movhi" and a "ori" and observe the one-to-one matching of some other instructions. Notice also how the constants defined with and ".equ" directive (such as ADDR_GREENLEDS) have been replaced by their numerical value in the machine code. Finally, notice that there exist some instruction blocks and meta-data that did not exist in the source code but have been added by the linker in the executable in order to help with the loading of your executable in the DE2 memory, for example the "_start" block of instructions and the ".stab" section. For more information on this topic, you can refer to the ELF format documentation.

5) Write your own assembly program

Create a new text file called test.s in the folder where you decompressed your DE2 package and copy the following assembly code into it:

    .include "nios_macros.s"
    .equ ADDR_7SEG, 0xff1100

    /* List of registers utilized:
    r2: pointer in array                 r6: index in the array
    r3: value displayed                  r7: temporary register
    r4: address of display               r9: counter in delay loop
    r5: length of the array                                        */

    array:
    .byte 1
    .byte 2
    .byte 3
    .byte 4

    .global main
    main:
    movia r4,ADDR_7SEG /* load address of display */
    movia r2,array     /* load address of array */
    movi r3,0          /* initialize value displayed */
    movi r6,0          /* initialize counter */
    movi r5,4          /* set length of the array */

    LOOP:
    bge r6,r5,amin     /* test for end of array*/

    ldb r7,0(r2)       /* load digit from array */
    or r3,r3,r7        /* add character to string of digits*/
    stwio r3,0(r4)     /* write to 7-segment displays /
    addi r2,r2,1       /* increment address */
    slli r3,r3,4       /* scroll string to the left */

    addi r6,r6,1      

    movia r99,10000000 /* set starting point for delay counter */

    DELAY:
    subi r9,r9,1       /* subtract 1 from delay */
    bne r9,r0, DELAY   /* continue subtracting if delay has not elapsed */
    br LOOP            /* delay elapsed, redo the LOOP */

This program prints an array of digits (1, 2, 3, and 4) on the hex display that scrolls to the left until the first digit reaches the 4th position, then the process repeats.

Compile and run your program by typing:

make SRCS=test.s run

6) Correcting errors in the source code

The assembler will report errors; try to fix all of them until your program is successfully assembled. Do this on your own and try to understand the compiler's error messages. ONLY IF YOU GET STUCK highlight the area below to see how to fix the above code (but again, you are highly discouraged from doing so - try to on your own). After it compiles, there is still a bug in the program! Try to use the debugger below to find it, if you can't come back here and highlight the whitespace below.

7) Observing your program with the debugger

To get familiar with debugging tools, type:

make SRCS=test.s debug

Open the window showing the content of the registers of the NIOS-II processor (View -> Registers )

Open the window showing the content of the memory of the NIOS-II processor (View -> Memory )

You should get a view similar to this:

The window labeled "Source Window" contains your source code. Lines are numbered on the left margin for your convenience. The line numbers in your window don't have to match the ones in the figure above. The green high-lite indicates where you program is stopped (notice that your program is no longer running because the 7-segment display is static).

The window labeled "Registers" shows a list of NIOS-II registers as well as their contents.

Finally, the window labeled "Memory" shows memory addresses on the left and the contents of those memory locations in the cells of the table.

7b) Modifying the state of the processor with the debugger

Let's take a closer look at the Memory window. Note that values in the table are displayed in groups of 4 bytes. Right now the table starts at address "$pc" ( "pc" stands for program counter), meaning that you are looking at the memory where your machine instructions are stored. In the NIOS-II processor, some of the addresses in the memory are mapped to hardware (you will hear about "Memory mapped I/O" later in this class). This is the case for the 7-segment display. It is located at address 0xff1100. Type 0xff1100 in the box next to the label "Address" in the Memory window and press Enter. In the top-left cell of the table, type 0x12345678 then Enter and notice how the the 7-segment display is immediately updated. The list of memory address ranges attached to physical memory or to hardware devices for a given processor is called its memory map.

You can also modify the value of registers in the Register window. This is useful if you want to force or initialize your software in a particular state.

8) Setting a breakpoint with the debugger

The debugger gives you the possibility of executing each of the instructions of a program one by one (a.k.a. stepping) to observe their impact and most importantly, to verify that the program is behaving as you expect it to. The first instruction of the program that we will step over is

movia r4,ADDR_7SEG

This instruction should move (i.e. copy) the address of the 7-segment display (0xff1100) to the register r4. Note the current value of the register r4 in the Register window and press the second icon of the tool bar in the Source Window once (the button Step attached to the keyboard shortcut s). Verify in the register window to see that the address of the 7-segment display (0xff1100) has been loaded in r4.

Continue stepping in your program (by pressing s). You will enter the DELAY loop, as shown in the following picture:

If you keep stepping, you will realize that it would take a large number of steps to exit this loop. The solution is to instruct the debugger to freeze the program at some instruction logically later in the program: in this case we want to resume debugging right after the delay loop. If we analyze where the delay loop occurs, we can see that the program counter first points to the "subi" instruction (line 33 in the figure above), then points to the instruction

bne r9,r0, DELAY 

(line 34 in the figure above). This last instruction is a conditional branch instruction that sets the program counter to the address indicated by the DELAY label if the value of register r9 is different than the value of register r0 (which is always 0). So the programmer intends to decrement r9 until it reaches 0 to create a delay (i.e. waste processor cycles). To leave the delay loop, we set a breakpoint in the program by clicking on the left margin of the code in the Source window as shown below:

Now let the program counter iterate through the delay loop and reach your breakpoint by pressing the Continue icon (attached to the keyboard shortcut C). Step one more instruction and observe what happens to the program counter. As you can see, there are other loops in this program: for example, the loop scrolling the characters one by one is defined by a label and a branch statement as follows:

    LOOP:
          ...
          ...
          br LOOP

Loop a few times in the program and verify that r6 is incremented on every loop iteration.

Can you identify a third loop in this program?

9) Exercises

Leave the debugger by closing the debugger windows and try your hand at editing assembly code.

1) Make the digits scroll continuously to the left in the 7-segment display, i.e. change the source code such that the 7-segment displays are not reset to all zeros.

2) Continuing from part (1), extend the array of digits with the digits 5, 6, and 7 and adjust the code to make this longer string scroll on the 7-segment display.

Verify that your code works. If you encounter problems, try stepping through the code with the debugger.

11) Summary

In this lab, you learned how to execute a program on the NIOS-II soft processor. You learned about the assembly language. You wrote, assembled and executed your own program that you further traced using the debugger. The debugger is a very powerful tool to find problems in your code: make sure that you are familiar with it before moving on to the next lab.

The command shell offers a set of commands similar to a Linux or Unix shell. Type ls c:/altera/71/quartus/bin/cygwin/bin/ to see a list of available commands. Most commands are documented online. Relevant commands are:

•   ls: lists the files in the folder; ls -l gives a more detailed output

•   less: lists a file while allowing to scroll back and forth with it. Use space bar or the arrows to scroll and q to exit.

•   cp: copies a file from its source to some destination

•   mv: renames/moves a file from its source to some destination

•   rm: erases a file

Productivity tricks:

• You can open multiple command shells.

• You can paste text in a command shell by clicking the right button of the mouse at the prompt. You can right-click on the title-bar of the command shell for more features.

• Use can use the arrows up and down to navigate your history of commands in the shell.

• You can press TAB if you want the shell to attempt to complete a file name that you started typing (the shell will complete up to the point where only one completion is possible; pressing TAB another time will list the available possible completions if there are more than one).

• ctrl-a moves the cursor to the start of the line

• ctrl-e moves the cursor to the end of the line

Appendix B) More information on the Makefile

A Makefile is a text file that is interpreted by a program called "make". A Makefile contains targets, for example "help" in make help is a target. We have predefined a number of targets for you in the Makefile to automate some operations and save you some typing. Some targets reference some variables (for example, the variable SRCS, that you set by typing make SRCS="test.s" run earlier). You can change the default definition of those variables at the top of the Makefile so that you don't have to specify them every time on the command line. To list the commands that would be executed in a particular target, type make -n and the name of the target. For example, try make -n debug. Look inside the Makefile using less Makefile and you should see entries in the following format:

When called with no target (i.e. simply make), the "make" program uses the first entry of the Makefile as the default target, otherwise, it uses the supplied target. It then ensures that the commands for the "dependent targets" of the requested "Makefile target" are executed, and this is applied in a recursive fashion. To see the process in action, first type make clean (to remove all the compiled files, as the "make" program uses time-stamps to only recompile updated source files) and then make SRCS="test.s" run. You should get an output similar to this:

Don't be scared by the long command lines as you will never have to type them. You should however understand what is happening. Remember that you first called the target "run". The Makefile specifies that $(TARGET).elf should be created first. Since we didn't give a value to the variable TARGET, it assumes its default value set at the beginning of the Makefile (i.e. "prog"). So "make" must first create "prog.elf". If you look carefully and mentally substitute variables for their value (including SRCS that you supplied at the command line), you will realize that "prog.elf" depends on "test.o" (and setup/crt0.o that is supplied to you). "test.o" is obtainable using the implicit target "%.o: %.s" that takes in a ".s" file and creates a ".o" (a.k.a. object file). This is called the assembly process and occurs on line 1 in the listing above. Then "prog.elf" can be created by linking the generated object files and the system object file (setup/crt0.o) together. This happened on line 2 and 3 of the listing above. Finally, the "run" target can be fulfilled: it consists of downloading the compiled program to the DE2 board using the USB port (as listed on line 4 above).