IS1200/IS1500 Computer Engineering - KTHIS1200/IS1500 Computer Engineering Laboratory Exercise nios2int – Interrupts and Traps ... code, use a flow-chart to explain what happens

IS1200/IS1500 Computer Engineering

Laboratory Exercise nios2int – Interrupts and Traps

Incomplete work is only valid until 2015-05-31

Latest update: 2014-11-06

Student's namein permanent ink: ________________________________ Date: ______________________

Demonstrations 1, 2, 3. There are no Demonstrations for these Assignments.

Demonstration 4: The Key

Discussion about working program,signed by teacher: _____________________

First Surprise Assignment. Teacher's description of Surprise Assignment:

___________________________________________________________

Demonstration 5: First Surprise Assignment. Signed by teacher: ________________

Demonstration 6: Toggles.

Discussion about working program,signed by teacher: _____________________

Second Surprise Assignment. Teacher's description of Surprise Assignment:

___________________________________________________________

Demonstration 7: Second Surprise Assignment. Signed by teacher: ________________

Laboratory Exercise 100% complete. Signed by teacher: ______________________Hey, student! Please keep this page, as proof of your completed laboratory exercise.

IS1500 nios2int 2014 page 1

This page intentionally left blank.


nios2int: Input and Output

Contents• Files used – a complete list, so you can download them all and then work offline ................3• Read this first – our best advice comes first ..........................................................................4• Objectives – what you will be able to do after the laboratory exercise ..................................5• Requirements for Laboratory Exercises – how to pass our laboratory exercises ...............5• Known issues ..........................................................................................................................6• Checklist for troubleshooting ...............................................................................................8• Exceptions and interrupts - how they work ........................................................................9• Interrupts ............................................................................................................................... 9• Exceptions ............................................................................................................................ 10• Exceptions or interrupts in an exception handler ........................................................... 12• Altera-supplied software functions ................................................................................... 13• Hardware information ....................................................................................................... 16• Toggle switches .................................................................................................................... 16• Red LEDs ............................................................................................................................. 17• Green LEDs ......................................................................................................................... 17• Push-buttons ........................................................................................................................ 18• Seven-segment displays .......................................................................................................19• The Programmable Hardware Timer ............................................................................... 19• Serial Port (UART,Universal Asynchronous Receiver/Transmitter) ............................ 21• Serial Input and Output ..................................................................................................... 22• Putty ......................................................................................................................................24• Assignments with Assembly-Language Interrupt Handlers ........................................... 25• Home Assignment 1 – Prime Time .................................................................................... 26• Home Assignment 2 – Exceptional Exclamation ............................................................. 29• Home Assignment 3 – T-Time ........................................................................................... 31• Home Assignment 4 – The Key .......................................................................................... 32• Laboratory Assignment 5 – First Surprise Assignment .................................................. 34• Home Assignment 6 – Toggles ........................................................................................... 35• Laboratory Assignment 7 – Second Surprise Assignment .............................................. 38• Laboratory Assignment 8 – Packing up the Board ..........................................................39• Error messages .....................................................................................................................42• Version history for this document ......................................................................................43

Files used

All files are available from the course web.

• You need a software installation of the Nios II Software Build Tools for Eclipse. The Nios II Software Build Tools for Eclipse is bundled with Quartus II, version 11 or later. If you install yourself, please select Quartus II version 13.0sp1, which is compatible with all laboratory exercises in this course. Later versions are not compatible.

• You need a configuration file for the Nios II Software Build Tools.

• You need the NIISim simulator.

• You need the Nios II Processor Reference Handbook (PDF) from Altera. We use chapters 3 and 8. Chapter 3 describes the programming model, and chapter 8 is the instruction set reference.


• You need a configuration file for the DE2 board.

The items above are the same ones you used for the Laboratory Exercises nios2time and nios2io.

• You will also need several source files, specific to this lab.

Read this first

This lab is 90% preparation. Really. You may need a full week to prepare completely for the laboratory session.

Do previous labs first. You must finish the First Project, and also labs nios2time and nios2io before you begin.

This lab session is more difficult. In this lab, the debugger is not as trustworthy as it used to be. An interrupt can cause the processor to execute a lot of code behind the debugger's back. The debugger can only tell you about things it knows about, so what you see in the debugger is no longer always true. You need to understand your own code really well to find out what's happening.

You will need the KTH-managed computers in the computer-rooms. Go there, and check that you can log in. If you can't, fix that. Otherwise, you may have trouble at the lab session, so that you are unable to finish the laboratory exercise.

Participate in our practicals (övningar). The lectures tell you the general picture, but our practicals discuss the details you need at the lab session. If you miss a practical, you will spend hours just catching up.

Check the solved sample exercises (Exempelsamling), and the slides from our practicals (övningar). There are lots of solved examples and useful slides to help you get going.

Explain every line of code to yourself. If you can't understand it, it shouldn't be there. And we will ask you to explain it at the lab session.

When you see an error message, check the list. If we have seen that message before, the list will contain good advice about what to do.

Use the debugger. When your program doesn't do what it should, step through it in the debugger. At each step, check carefully that the program really does what you want. If it does something else, you've found the error.

There is a trick to set a breakpoint at the start of your interupt handler. Start the debugger, then write down the current program-counter value. Now change the program counter to 0x800020. Step once, so that the interrupt-handler starts. Step twice again. You are now inside your own exception handler. Set a breakpoint there. Now change the program counter back to its original value, so that your initialization code gets to run correctly. This procedure ensures that the debugger will stop on every interrupt. If it doesn't stop, this means that there was no interrupt; and that can be a very useful piece of information, too. Important! When performing this procedure, please remember to change the program counter back to its original value, so that your initialization code runs correctly.

Perform code review. Read through your program carefully and try to improve it. Make notes of the contents of selected registers to check that the program really does what you want.

Ask us. If you get stuck, get help. Post a question on the KTH Social Course Web. We follow these questions and reply as soon as we can, and other students can post a reply even faster than that.


Objectives

After this laboratory exercise, you will be able to:

• write assembly-language interrupt handlers • write assembly-language trap handlers • write C-language interrupt handlers • write interrupt handlers combining assembly language and C

Requirements for Laboratory Exercises

Do all Home Assignments before the lab session. We will send you home if your Home Assignments are incomplete.

All code must be easy to understand. The best way is to make it short and simple. When you must do something non-trivial, write a comment to explain. When you reach 15-20 lines of assembly code, use a flow-chart to explain what happens. Complicated code means confusing code.

All code must follow our specifications completely. In this laboratory exercise, you will create building blocks to be used for later lab exercises, together with code written by other people. Your building blocks will only work with the other building blocks, if all your code follows all specifications completely. "But it works anyway" is not an excuse - it means you've taken some shortcut instead of writing correct code. Sloppy code can fail miserably at the next laboratory exercise, when you've forgotten about your shortcuts.

All your code must compile with no errors and no warnings. To check this, right-click the project name and select Clean Project, then right-click again and select Build Project. Look for messages in the Problems tab, and in the Nios II Build Console.

Be prepared to explain. The laboratory teachers ask questions about your programs, and every student must be able to explain everything, individually. We will send you home if you cannot explain your code. It's your code – you must explain it.

Be prepared to change your code. You will get Surprise Assignments, which you must finish during the lab session. If you can't finish a Surprise Assignment, you must come back at a later lab session. At that later session, you will get a new Surprise Assignment, which must be finished at that session. You can never take home a Surprise Assignment.

You must complete all Laboratory Assignments, demonstrate them and explain them. All Assignments are mandatory.

Work in groups of two. We will have 15 DE2 boards for a group of 30 students. You can sometimes work alone, but check with the laboratory teachers first. Groups of more than two persons are not allowed. This rule is not negotiable.

At the lab session, show us immediately. As soon as you have finished a Demonstration: discuss with the lab teacher, who will mark your work on the front page.

Keep the front page. When you've Demonstrated everything, the teacher will make a note on our department-internal list. This list is later used for reporting into Ladok. The front page is your safeguard, in case any errors should occur in our department-internal list.


Known issues

Wonky push-buttons

On many boards, the push-buttons KEY3, KEY2, KEY1 and KEY0 are unreliable. If they don't work, press a harder. If this doesn't help, press at the edge of the button intead of in the center.

All other buttons and functions on the boards work perfectly.

Where's my output?

During simulation, you will see all program output in the UART0 console-window of the NIISim simulator. At the laboratory session, there are three possible cases. Which one you will see depends on the internal design of your computer.

1. Most common case: Your computer has no serial-port hardware, so the Nios II IDE gives an error message. You will need a USB-to-serial converter (we supply that) and a terminal emulator (you fix that!). The error message is: nios2-terminal: can't open uart: Permission denied, and/or Terminal process failed. Just click OK, and ignore those two error messages.

2. This case can happen: Your computer has serial port hardware but no connector, so you can't use it. You will need a USB-to-serial converter (we supply that) and a terminal emulator (you fix that!). There will be no error messages, since the Nios II Software Build Tools will connect to the (unused) internal serial port. However, nothing will be displayed in the console window of the Nios II Software Build Tools.

3. Least common case: Your computer has a serial port, and you use it. Program output is displayed in the console window of the Nios II Software Build Tools.

movia bug

The movia pseudo-instruction produces incorrect code for negative constants, and for values larger than 0x80000000. That's 7 zeroes, so all valid DE2-board addresses are safe. Memory starts at 0x800000 (only 5 zeroes).

An important case is moving -1 to r2: please use movi r2,-1 In this case, movia will not work. The assembler translates movia incorrectly, changing the contents of another register. Nearly all negative constants can use movi without the a.

All movi instructions (without the a) work correctly, but have a 16-bit size-limit. Constants for movi must be in the range -32768 through +32767.

jmpi

The hardware has no jmpi instruction. If you use it, your code will fail at the lab session.

.include

You can only use .include for files containing macro definitions. Files containing subroutines may not be included. Otherwise, some code will be compiled twice (or more), and the duplicates will cause errors and endless confusion.

Files containing program text and/or data must never be included using .include.


http://www.ict.kth.se/courses/IS1200/2014/swsetup/hypertrm.html




PUSH

The definition of the PUSH macro must use subi sp,sp,4 and not addi sp,sp,-4

This is confusing, since these two instructions should be translated to the exact same bits in the binary machine-code program.

Changing files outside the Nios II Software Build Tools

It is possible, but not recommended, to use other programs than the Nios II Software Build Tools to edit C-code files, assembly-code files, and other source-code files. It is also possible to copy files through the Windows Explorer or other file-manager program.

Remember to right-click the project directory in the Nios II Software Build Tools window, and select "Refresh" every time you have changed a file outside the Nios II Software Build Tools.

This applies to all projects affected by a change, so moving a file from one project-folder to another will normally require two Refresh operations, one for each of the two projects.

Only copy, edit, and move source files.

Never change, copy or move configuration files.

Never copy or move folders, because folders always contain configuration files.

The Nios II Software Build Tools stores administrative information in hidden files. These hidden files contain path information, which becomes invalid if the file is copied or moved.

If you happen to copy or move a hidden file, you will confuse the Nios II Software Build Tools. The resulting error messages are usually incomprehensible, and seemingly totally irrelevant.

The Debugger may hang instead of starting normally

This can be fixed, see Fixing the Debugger if it hangs.

Run As Hardware produces an error, but my program is unchanged since the last run

This can be fixed, see Target Connection Problem on page 43.


Checklist for troubleshooting

There is also a (partial) list of error messages at the end of this document.

• .data before data • .text before code • .align 2 before code • .global is required for the name of each subroutine. • .end causes the assembler to stop assembling. Don't put anything after .end. • No code before main: When starting your program, the Nios II processor is initialized by a

startup-routine. The startup-routine calls your code with the instruction call main Therefore, any code before the label main: will never be executed.

• Subroutines: Must be called with call or callr and returned from with ret • Parameter to subroutine: must be in r4 • R31: Any subroutine that calls other subroutines must push r31 before the first call, and

pop r31 after the last call. • If you use any of r8 through r15 for local variables, you need to caller-save those registers

by pushing them on the stack before any subroutine call, and restore them by popping from the stack afterwards.

• If you use any of r16 through r23 for local variables, you must save those registers before you first write them, and restore the original values before you return from your subroutine.

• Always save to the stack. There are no safe registers. If you think there are safe registers, your programs will fail miserably at the nios2int exercise.

• Always use ldwio to read from an input/output device, and use stwio to write to it. • Start the terminal-emulator window with correct port-parameters. Use 115200 bits/s, 8 data

bits, no parity, 1 stop bit, and no flow control. • Keep the terminal-emulator running. Closing it and restarting it is a waste of time.• Check the UART addresses. Address for uart0 = 0x860, address for uart1 = 0x880. • If you type one character and get lots of copies of it in return: perhaps there's a problem with

the check for negative return values indicating "no new data" . • Anything you save to the stack will disappear when your subroutine returns. If you need to

remember things until the next time your subroutine is called, use a variable in the DATA area in main memory. These variables are sometimes called static, since they still exist whether your subroutine is running or not.

• Symbols are sometimes case sensitive, so hexasc and HEXASC may be different labels in some cases (but not always). Therefore, always write all labels and names the same way, 100% of the time.


Exceptions and interrupts - how they work

Interrupts

This is a summary of the Exception Processing sections of Chapter 3 from the Nios II Processor Reference Handbook.

An interrupt happens when a hardware device changes an electrical signal from inactive (0) to active (1). As an example, the hardware device may do this when input data are available. The electrical signal passes through logic gates, allowing other inputs of those gates to block the signal. When the signal is blocked, the interrupt is disabled (and cannot happen).

This figure shows a general interrupt signal in a Nios-II system.

The input/output device has some kind of internal ready-signal, for example to indicate that fresh data is available. A configurable interrupt-enable bit in the device controls whether this ready-signal can be seen outside the device.

If the ready-signal is available outside the device, it is connected to one of the 32 interrupt-request inputs of the Nios II processor. The inputs are numbered 0 through 31. Each input has a corresponding bit in the ienable control-register, so that interrupts can be enabled and disabled for each device separately.

A global flag, the Processor Interrupt Enable bit, is used to enable or disable interrupts in general.

The figure below shows a simplified logic diagram of the interrupt-logic inside a Nios II processor.

Every device has a unique bit in the ipending special register (ctl4), and the interrupt-handler must check which bit is a '1'. For example, if bit 2 is a '1', there was an interrupt from device number 2. The handler must figure that out, and then jump to code that is specific for the device connected to interrupt-input number 2.

While an interrupt is being processed, all further interrupts are disabled. The processor ensures this by clearing the Processor Interrupt-Enable bit (PIE) in the status register (ctl0) before starting the interrupt handler. The eret instruction restores the previous contents of the status register.

When interrupts are enabled, an interrupt can happen anytime, so all registers can be expected to contain values needed by the interrupted program. Therefore, an interrupt handler (also known as an interrupt service routine) can never modify any register contents.


In the Nios II processor, register R24 is set aside for temporary use by interrupt handlers. Register R24 is also called et (exception temporary). Interrupt-handlers that needs to use other registers must first save their values to the stack, and restore those values before returning.

In Nios II systems, interrupts always cause the processor to jump to one specific address. In the systems used in these laboratory exercises, the address is 0x800020.

Return from the interrupt must be by way of the special exception-return instruction eret

Since interrupts are disabled in an interrupt handler, some functions are not available. In particular, the putchar function must never be called from an interrupt-handler, since putchar uses an interrupt-dependent device (the JTAG UART).

Calling putchar from an interrupt handler fails in the following way: putchar will sometimes wait for an interrupt from the JTAG UART. Since interrupts are disabled, that interrupt will never happen, so the system hangs until you restart it.

Exceptions

A software exception has the same effect as an interrupt, but the cause is different. Interrupts are caused by hardware outside the processor, but a software exception is caused by some specific instruction that is executed in the processor.

On many systems, the division instruction will cause a software exception if the divisor is zero (a divide-by-zero exception). There is also a trap instruction, that will always cause a software exception.

Since software exceptions and interrupts are similar, they are often discussed together. In this case, an "exception" is either an interrupt or a software exception.

An exception wrapper for C

It is not possible to write an exception handler using only C. Some assembly-language code is necessary. In some of the Assignments in this laboratory exercise, you will use an Altera-supplied exception-wrapper. This wrapper is written in assembly language, with some parts in C.

The general structure of the wrapper is as follows. For more details see the section on Altera's exception-handling wrapper.

1. Save register ra (return address, r31) plus all caller-save registers (registers r1 through r15). 2. Save control register estatus (contents of status as it was just before the exception, ctl1).3. Call a C-language checking-routine to find the cause of the exception. If the cause was an

interrupt, the C-language routine looks in the ipending special register (ctl4), to find out which one of the 32 interrupt inputs was active. Each interrupt input has its own interrupt-handling subroutine. The checking-routine selects the right subroutine and calls it.

4. After the return from the C-language checking-routine, restore all previously saved register contents (registers r1 through r15, ra, and estatus).

5. The last instruction of the wrapper is eret, which returns to the interrupted program.

If you write an interrupt-handling subroutine that the exception-wrapper should call, you must make your subroutine known to the C-language part of the exception-wrapper. An interrupt-handling subroutine is often mentioned as an "Interrupt Service Routine" (ISR), and making an ISR known to the exception-wrapper is desribed as "registering the Interrupt Service Routine". See below for more information.


http://www.ict.kth.se/courses/IS1200/2014/nios2int/index.html#sw

The figure below shows actions that must be taken by a general interrupt wrapper.

Exceptions without a wrapper

You can't rely on other people to write wrappers for you at all times. To have your own, complete exception handler for Nios II, the following steps are necessary. Please note that all steps below refer to assembly-language program code.

1. As part of your initialization, copy a stub routine to the exception-handling address 0x800020. The stub routine should contain a jmp instruction, transfering program control to your main exception handler.

2. In your main exception handler, do the following: 1. Check if EPIE == 1; if not, there was no interrupt (but perhaps a trap or other

synchronous exception). EPIE is the saved value of the Processor Interrupt-Enable bit, from immediately before the interrupt (or trap or exception). EPIE can be read from the special register estatus (ctl1).

2. If EPIE == 1, check if ipending == 0. If ipending == 0, there was no interrupt (similar case as in the previous check). ipending is a special register (ctl4).

3. If EPIE == 1 and ipending ≠ 0, the exception was caused by a hardware interrupt. Subtract 4 from the saved exception-return address in register ea (r29), since the interrupted instruction was not finished and must be restarted.


4. Check one of the bits in the ipending special register (ctl4). If this bit is set, there is an interrupt pending corresponding to the index of that bit. In that case, control must be transfered to your Interrupt Service Routine for that interrupt index. In assembly-language code, you would normally use a branch or jump instruction for this, and not a call, so the Interrupt Service Routine should end with an eret instruction.

5. Check another bit in the ipending special register (ctl4). And so on, for all possible interrupt sources.

6. Please note that the order in which you check the bits will decide the relative priority of different interrupts. Interrupts checked first will have priority over interrupts checked later.

3. Check if the interrupted instruction was a trap. If so, jump to a trap handler. 4. Theoretically, you would want to check if the interrupted instruction was an unimplemented

instruction, for which you have written a handler. This is beyond the scope of this laboratory exercise. You may ignore the case of unimplemented instructions: you don't have to check for them in this laboratory exercise.

5. Add code to handle the case that no trap, interrupt, or unimplemented instruction caused the exception. This is called a spurious interrupt.

The steps above are adapted from the section Determining the Cause of Interrupt and Instruction-Related Exceptions in Chapter 3 of the Nios II Processor Reference Handbook.

Exceptions or interrupts in an exception handler

In rare cases, it is necessary to allow an interrupt handler to be interrupted. There are two possible cases: allowing the same type of interrupt to happen again, and allowing other interrupts to happen (but not the same type as the one we're handling).

A software exception or trap inside an exception handler must be handled similarly. In the lists below, steps not applicable for traps are clearly marked.

Note: the Altera-supplied exception wrapper saves (and restores) ea and estatus.

Allowing all interrups, including allowing the same type of interrupt to happen again (using Assembler)

This requires the following steps:

1. Acknowledge the interrupt. This step must be performed before the interrupt-enable step below.

2. Save the contents of register ea (r29 - the exception-return address register). 3. Save the contents of special register estatus (ctl1). 4. Enable interrupts for the current interrupt number (not required for traps). 5. Do whatever it is that will take such a long time (long enough for you to want interrupts

enabled for the duration), or do whatever it is that may cause a software exception or trap. 6. Disable interrupts (not required for traps). 7. Restore the contents of special register estatus (ctl1). 8. Restore the contents of register ea (r29). 9. Return normally from the interrupt, using eret.


http://www.ict.kth.se/courses/IS1200/kompendier.html

Allowing other interrupts, but not the same type again (using Assembler)


1. Save the contents of register ea (r29 - the exception-return address register). 2. Save the contents of special register estatus (ctl1). 3. Disable interrupts for the current interrupt number (not required for traps). 4. Enable interrupts for all other interrupt numbers (not required for traps). 5. Do whatever it is that will take such a long time (long enough for you to want interrupts

enabled for the duration), or do whatever it is that may cause a software exception or trap. 6. Disable interrupts (not required for traps). 7. Acknowledge the interrupt. This step may be performed earlier in the sequence. 8. Restore the contents of special register estatus (ctl1). 9. Restore the contents of register ea (r29). 10.Re-enable interrupts for the current interrupt number (not required for traps). 11.Return normally from the interrupt, using eret.

Executing a trap instruction from within an exception handler (using Assembler)


1. Save the contents of register ea (r29 - the exception-return address register). 2. Save the contents of special register estatus (ctl1). 3. Save all caller-saved registers (r1 through r15).4. Execute the trap instruction.5. Restore the contents of special register estatus (ctl1). 6. Restore the contents of register ea (r29). 7. Return normally from the interrupt, using eret.

Altera-supplied software functions

This section contains more information on the Altera-supplied exception wrapper, and on some relevant functions/subroutines.

The Altera-supplied exception wrapper can handle all sorts of interrupts, but only some types of software exceptions. In this Laboratory Exercise, we will only use the wrapper for interrupts, and not for any software exceptions.

Registers saved and restored by the exception wrapper

The following registers are saved and restored by the exception wrapper:

• Register r31 (the subroutine-return address register, ra). • Register r1 (the assembler's temporary, at). • Registers r2 through r15 (the caller-saved registers). • Control register estatus, also known as ctl1. Saving this register is strictly necessary only

in interruptible handlers, but always saving it simplifies the code.

Registers r16 through r23 are not in this list; they are the callee-saved registers. Since callee-saved registers must be saved and restored by any function/subroutine using them, they need not be saved by the wrapper.


Registering an interrupt handler

Let's recall how interrupts are handled by the Altera-supplied software. The Altera-supplied assembly-language wrapper calls a C-language checking-routine. This checking-routine examines the cause of the exception. If it was an interrupt, it checks the ipending special register (ctl4) to determine which device caused the interrupt. Every device has a unique bit in the ipending special register (ctl4). For example, if bit 2 is a '1', there was an interrupt from device number 2.

The checking-routine uses a table, mapping device numbers to interrupt-handling subroutines. If you write an interrupt-handling subroutine (Interrupt Service Routine, ISR), the starting address of your subroutine must be put into the correct cell of the table. This is called registering the Interrupt Service Routine.

The Altera-supplied function for registering an Interrupt Service Routine is alt_ic_isr_register. A call to this function has five (5) input parameters, like this:

check_val = alt_ic_isr_register( ic_id, irq_number, function, context, flags );

irq_number is the interrupt index (device number), and function is the starting address of your Interrupt Service Routine. For ic_id use the numerical constant 0 (zero); for context and flags use a null-pointer (a pointer with the value zero). There's a detailed example below.

Upon return from alt_ic_isr_register, the interrupt with index irq_number is enabled. The return value (check_val) is zero for success and non-zero in case of failure.

All other interrupts are unchanged by alt_ic_isr_register. Interrupts which were previously enabled are still enabled, and interrupts which were previously disabled are still disabled.

Type declarations

In order for your program to be type-correct, you must make sure that variables and functions have declarations conforming to the Altera-supplied definitions. Here's a summary:

void irq_handler( void * context ); /* You write this handler! */int alt_ic_isr_register( alt_u32 ic_id, alt_u32 irq_number, void (*function)(void *, alt_u32), void * context, void * flags ); /* Written by Altera */

The declaration for irq_handler is simple and has only one (1) input parameter. This is good, as you must write that handler and use exactly that declaration. You can change the names (irq_handler and context), but not the types (void, and pointer to void).

The declaration for alt_ic_isr_register is not-so-simple. But Altera has already written the declaration - it's in the include-file alt_irq.h. All you have to do is call alt_ic_isr_register and supply the right five parameters. Let's go through them one by one.

1. The ic_id parameter must be 0 (the integer constant zero). In more complex Nios II systems there can be more than one interrupt-controller, and this parameter selects which one to use.

2. The irq_number parameter must be an integer constant equal to the interrupt-index of the hardware device causing the interrupt. So if you're writing a handler for interrupts from uart_1, irq_number must be 5. No other number will work, since the hardware was designed with uart_1 connected to the processor's interrupt input number 5.

3. The function parameter is simply the name of your interrupt handler. Altera's interrupt-handling wrapper-code will save this parameter, and call your handler when there is an interrupt on the input you specified with the irq_number parameter (described previously). This kind of mechanism is called a call-back.


4. The context parameter should be a null-pointer: ((void *) 0). The pointer value will be a parameter to your handler, when Altera's wrapper-code calls it. This is useful in more complex setups, but not in this laboratory exercise.

5. The flags parameter is reserved for future use by Altera, and must be a null-pointer: ((void *) 0).

Example

Some sample code will give an even clearer picture. This sample code initializes a device called somedevice with interrupt index 7:

#include <alt_irq.h>const int somedevice_irq_index = 7; /* IRQ number for somedevice */void * null_pointer = (void *) 0; /* Null pointer for calls to alt_ic_isr_register */void irq_handler_for_somedevice( void * context ){ /* Insert real handler code here. This is just an example. */}void initialize_somedevice( void ){ int check_value; /* Insert real initialization code here. This is just an example. */ check_value = alt_ic_isr_register( 0, somedevice_irq_index, irq_handler_for_somedevice, null_pointer, null_pointer ); if( check_value != 0 ) my_initialization_failed_with_an_error(); /* Change this to code for handling the error. */}

The header file alt_irq.h must be included, so that the compiler can recognize alt_ic_isr_register and other relevant functions. The code in the handler may ignore its argument; but the argument must be present, or your program will not compile. In our example, we don't use the context parameter, so we set it to a null-pointer in the call to alt_ic_isr_register.

On an interrupt, your handler (irq_handler_for_somedevice) is called by Altera's wrapper. The argument, context, is the pointer (null_pointer) you used when you registered the handler.


Hardware information

Toggle switches

Example: reading address 0x850 will return 14 unspecified most-significant bits, and 18 least-significant bits indicating the current positions of switcher SW17-SW0.

The interrupt-mask must be written during initialization. For every toggle-switch, there is a bit in the interrupt-mask. Setting a bit to '1' enables interrupts when that switch is moved from one position to the other. With interrupts enabled, both possible position-changes will interrupt the processor. Moving the switch lever towards the center of the board will produce an interrupt, as well as moving the switch lever towards the edge of the board.

There's a bit for every toggle-switch In the edge-capture device-register, too. When a switch position was changed, the corresponding bit in the edge-capture device-register is set to 1.

It is not possible to clear individual bits of the edge-capture device-register. Any write operation to address 0x85c will clear all bits of the edge-capture device-register, regardless of the value written.

To enable interrupts for one or more toggle switches:

1. Setup an interrupt handler for the interrupt-requests from device number 3 (de2_pio_toggles18). How to do this depends on your software configuration.

2. Set (to a logic "1") those bits in the interrupt-mask (0x858) which correspond to toggle switches that should be able to interrupt the processor.

3. Set (to a logic "1") the bit with index 3 in the processor's ienable register (ctl3). A bit-mask with this bit set is: 0x0008.

4. Set (to a logic "1") the processor's PIE bit (Processor Interrupt Enable) - bit 0 in the status register (ctl0).

The interrupt output from de2_pio_toggles is active if and only if: there is a '1' in some position in the edge capture register, and also a '1' in the same position in the interrupt-mask register. When this condition is true, other bits in the edge-capture and interrupt-mask registers do not matter. To acknowledge the interrupt, write any value to the edge-capture register. This will always clear all bits of the edge-capture register.


Red LEDs

Example: writing the value 0x17 to address 0x810 will light LEDs LEDR4, LEDR2, LEDR1, and LEDR0.This device cannot be a source of interrupts.

Green LEDs

Please note that LEDG8 is located between the blocks of seven-segment display-digits.

Example: writing the value 0x117 to address 0xA10 will light LEDs LEDG8, LEDG4, LEDG2, LEDG1, and LEDG0.This device cannot be a source of interrupts.


Push-buttons

The key-output is inverted, so when no-one touches your board, you will read 1's from the PIO. Example: reading address 0x840 when no-one touches the board will return 1's in the 4 least-significant digits (and unspecified values in the 28 most-significant digits).

The interrupt-mask must be written during initialization. For every button, there is a bit in the interrupt-mask. Setting a bit to '1' enables interrupts when that button is pushed, or released. With interrupts enabled, both possible position-changes will interrupt the processor. Pushing the button will produce an interrupt, as well as releasing the button.

There's a bit for every button In the edge-capture device-register, too. When a button was pressed or released, the corresponding bit in the edge-capture device-register is set to 1.

It is not possible to clear individual bits of the edge capture device-register. Any write operation to address 0x84c will clear all bits of the edge capture device-register, regardless of the value written.

To enable interrupts for one or more push-button switches:

1. Setup an interrupt handler for the interrupt-requests from device number 2 (de2_pio_keys4). How to do this depends on your software configuration.

2. Set (to a logic "1") those bits in the interrupt-mask device-register (0x848) which correspond to toggle switches that should be able to interrupt the processor.

3. Set (to a logic "1") the bit with index 2 in the processor's ienable register (ctl3). A bit-mask with this bit set is: 0x0004.


The interrupt output from de2_pio_keys is active if and only if: there is a '1' in some position in the edge capture register, and also a '1' in the same position in the interrupt-mask register. When this condition is true, other bits in the edge-capture and interrupt-mask registers do not matter. To acknowledge the interrupt, write any value to the edge-capture register. This will always clear all bits of the edge-capture register.


Seven-segment displays

The seven-segment display modules need two I/O ports for all their bits. Each display digit uses 7 bits. The decimal points are not connected. Bits cleared (logic "0") light up their corresponding segments; bits set (logic "1") shut off their corresponding segments. This device cannot be a source of interrupts.

The Programmable Hardware Timer

All device registers in the Timer have 32 bits (4 bytes) and must be read with an ldwio instruction (and written with a stwio instruction). However, no more than 16 bits (2 bytes) are connected. So the 32-bit period must be split into two 16-bit halves.

To initialize the timer, first write the 2 low bytes of the period to periodl, and then write the 2 high bytes to periodh. Finally, write once to the control register, setting the Start bit, (if appropriate) the Continuous-Mode bit, and (if appropriate) the Interrupt-on-Time-Out (ITO) bit.

Note: the timer counts down in one clock cycle, and sets the Time-Out flag in the next cycle if the counter reached zero. For example, if you want a 1000-cycle timeout, set the period value to 999.


Timer device-register summary

• Status, 0x920 - read status bits, write any value to clear Time-Out bit. • Control, 0x924 - write to start and/or control the timer. All bits are important, every time

you write. • PeriodL, 0x928 - write low bits of period here. Writing may stop the timer. • PeriodH, 0x92c - write high bits of period here. Writing may stop the timer. • SnapL, 0x930 - read low bits of latest snapshot, write to take a snapshot. • SnapH, 0x934 - read high bits of latest snapshot.

Bit by bit, explained

• Time Out (TO) - bit 0 at address 0x920 - set to one by the Timer when the counter reaches zero. To reset the Time Out bit to zero, the program must write to address 0x920. Whatever value is written is ignored. The write transaction causes the Timer to reset the Time Out bit.

• Run - bit 1 at address 0x920 - indicates whether the Timer is running or not. This bit is set to one by the Timer when counting starts and reset to zero by the Timer when counting is finished.

• Continuous Mode - bit 1 at address 0x924 - this bit can be set and reset by the programmer. If this bit is set to one, the Timer will restart itself immediately after counting reaches zero. The Time Out bit will be set to one each time the counter reaches zero. The Run bit will always be 1.

• Start - bit 2 at address 0x924. When a value, where bit 2 is equal to "1", is written to address 0x924, the Timer starts counting. Writing values where bit 2 is equal to "0" has no effect.

• Stop - bit 3 at address 0x924. When a value, where bit 3 is equal to "1", is written to address 0x924, the Timer stops counting immediately. Writing values where bit 3 is equal to "0" has no effect.

• Snapshot - to read the current counter value, write any value to address 0x930 (SnapL). The counter value at the time of the write transaction will be copied from the counter to a Snapshot register inside the timer. The Snapshot register can then be read at addresses 0x930 (lowermost 16 bits at this address equals lower 16 bits of counter snapshot value) and 0x934 (lowermost 16 bits at this address equals upper 16 bits of counter snapshot value).

Enabling periodic timer interrupts

1. Setup an interrupt handler for the interrupt-requests from device number 10 (timer_1). How to do this depends on your software configuration.

2. Initialize the periodl and periodh device-registers of the timer. 3. Set the Start, Continuous-Mode, and Interrupt-on-TimeOut bits in the control device-

register. These bits have indices 2, 1 and 0, respectively. A bit-mask with these three bits set is: 0x0007.

4. Set (to a logic "1") the bit with index 10 in the processor's ienable register (ctl3). A mask with this bit set is: 0x0400.


To acknowledge a timer interrupt, write any value to address 0x920.


Serial Port (UART,Universal Asynchronous Receiver/Transmitter)

uart_0 uart_1ReceiveData (RxD) Register Address 0x860 0x880TrasmitData (TxD) Register Address 0x864 0x884

Status Register Address 0x8680x888

Control Register Address 0x86C 0x88C

Bit by bit, explained

• Receiver Ready: when bit 7 in the Status Register is a "1", a new byte has been received; this byte can be read from the RxD Register.

• Transmitter Ready: when bit 6 in the Status Register is a "1", a new byte may be written to the TxD Register; this byte will then be sent out by the serial port.

• The serial port registers must be read and written as 32-bit words (with the ldwio/stwio instructions), but only the 8 least significant bits are of interest.


Notes and hints

• The RxRdy status bit is cleared when a byte is read from RxDATA. • The least significant bit is called bit 0. • If you need a bit mask with bit number x set to 1, and all other bits zero, write a binary 1

followed by exactly x binary 0's. • The assembler understands binary constants. Start them with 0b, for example 0b101 (that's

5 decimal). • You will most likely want interrupts only from RxRdy, and not from TxRdy.

Enabling interrupts from uart_0

1. Setup an interrupt handler for the interrupt-requests from device number 4 (uart_0). How to do this depends on your software configuration.

2. Set the enable bit (or bits) for interrupts from RxRdy and/or TxRdy in the control device-registers of the UART.



To acknowledge interrupts for received data, read input data from RxDATA.To acknowledge interrupts for transmitter-ready, write output data to TxDATA.

Enabling interrupts from uart_1

1. Setup an interrupt handler for the interrupt-requests from device number 5 (uart_1). How to do this depends on your software configuration.

2. Set the enable bit (or bits) for interrupts from RxRdy and/or TxRdy in the control device-registers of the UART.



To acknowledge interrupts for received data, read input data from RxDATA. To acknowledge interrupts for transmitter-ready, write output data to TxDATA.

Serial Input and Output

Your program will produce output using the out_char subroutine. This routine sends one character to the serial port uart_0 on the DE2 board. A serial cable connects this serial port to a similar port on your laptop, or on the stationary computer in the managed computer room. You will have a related subroutine for reading input arriving at the same serial port.

Serial ports uart_0 and uart_1 are described above, in the hardware section.

A serial-port connector looks is shown in the photo to the right.


At the lab session, use the serial port of the KTH-managed computer at your seat.

If you have your own computer, run the Nios II Software Build Tools on your computer, as usual.

The DE2 board will have three cables connected:

1. Power cable (of course),

2. USB cable, connected to the computer running the Nios II Software Build Tools (such as, your portable computer), and

3. serial cable, connected to the KTH-managed desktop computer.

Log in to the KTH-managed computer using your usual KTH login, also known as the KTH-ID.

Use the Putty program for input and output through the serial port.

Connect the serial cable to a serial-port on the KTH-managed computer. Do not connect the serial cable to the DE2 board yet. The serial-port will be on the back of the computer.

If there is no serial-port, the laboratory teacher will lend you a USB-to-serial adapter. Connect the USB-to-serial adapter to a USB port on the KTH-managed computer before you continue.

USB-to-serial adapter (only when no serial port is present)

Before starting your terminal-emulator, you need to check the name of your serial port.

Windows systems: open the Device Manager to check the port number. To open the Device Manager in Windows 7, click Start, then type "device manager" (or "enhetshanteraren" on a Swedish-language system). Click the Device Manager icon when it appears.

In the Device Manager window, open the section Ports (COM & LPT) by clicking the appropriate plus-sign. Check the COM port number of the USB to Serial Bridge. Important: If you unplug the USB-to-serial adapter and connect it to a different USB port, the COM-port number will be different.

Nothing will break if you use the wrong COM port. But the lab won't work, of course.

Linux systems: insert the USB plug into a free USB jack on the computer. Do not connect the DE2 board yet. The adapter is nearly always called: /dev/ttyUSB0

If you really must run putty on your own computer

We recommend that you run putty on a computer owned by KTH. If you really want to run putty on your own computer, you can. If you have Windows 8, ask the laboratory teacher for a USB-to-serial converter converter suitable for use with Windows 8. To get the driver, please visit aten.com, mouse over "Support" and click "Software and Driver". Then select "UC232A" in the drop-down list. Scroll down a little to see the driver downloads for Windows 7 and Windows 8.


Putty

Start Putty, and leave it running. Don't close and restart Putty, unless you have a USB-to-serial adapter and must disconnect and reconnect the adapter.

Stopping the terminal-emulator will not stop your program, which is running all by itself on the DE2 board. Stopping the terminal-emulator just means that Windows (or Linux) will have to buffer up your program-output, possibly making your system slow and unresponsive.

Windows systems: to start Putty, click Start, then type "putty". Click the icon when it appears. If this doesn't work, download Putty from http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html

Linux systems: to start Putty, open a Terminal and type: putty

You will see the Putty Basic Options Configuration screen:

Start by setting the Connection Type to Serial. Then click the Serial category in the left-hand pane.


You will see the Putty Serial Configuration screen:

Set Serial line to connect to to the correct serial port.

If the KTH-managed computer has a serial port, it's called COM1 or COM2. If you use a USB-to-serial adapter, you know the COM-port number from your check with the Device Manager.

Use speed 115200 baud and no flow control. Click Open.

Note 1: If you unplug the USB-to-serial adapter and connect it to a different USB port, the COM-port number is often different afterwards.

Nothing will break if you use the wrong COM port. But the lab won't work, of course.

Note 2: if you forgot to set the Connection Type to Serial, Putty will not respond when you click Open. Go back to the Session category and follow our instructions carefully.

Assignments with Assembly-Language Interrupt Handlers

Assembly-Language Assignments

Assignments 1 through 5 will not use the Altera-supplied wrapper. You will have to write your own code for most of the interrupt-handling functions. To get you started, we provide you with files for Assignments 1 through 5, available in a zipped archive called nios2int2014asm.zip.

In previous Laboratory Exercises, we used the putchar function. However, the putchar function uses the complex JTAG UART, which we will avoid in this lab exercise. Instead, we use uart_0.Therefore, you must create a new System Library. The procedure to do this is described below.


Home Assignment 1 – Prime Time

You can use the NiiSim simulator to test your programs for this Home Assignment. At the laboratory session, you will use a DE2 board to run your programs on Nios2 hardware.

Note: Instruction-set simulation carries a performance penalty. Simulated execution may be 10-1000 times slower than hardware. If interrupts are setup to occur 10 times per second, you can expect simulated interrupts to occur about every minute or so. Performance may vary considerably from time to time, from program to program, and of course from host computer to host computer.

Task preliminaries

HA1.1. Create a new Nios II Application and BSP from Template in the Nios II Software Build Tools. Call the project nios2int1.

HA1.2. Copy the files nios2int1main.s and nios2intasmhelpers.c) to the project folder.

HA1.3. Copy the files puttime_uart_0.c and tick.c into the project folder.

HA1.4. Right-click the project name and select Refresh, so that the Nios II IDE re-checks the contents of the project directory.


HA1.5. Test the program using the NIISim simulator. Open the UART0 console (not the JTAG UART) - this applies to all assignments in this laboratory exercise. Typical output from a short run can look like this:

HA1.6. Study the file nios2int1main.s until you understand the contents. Edit the file as specified below. Use the existing comments to guide your placement of the various code sections you write. Add comments detailing how your own code works.

• Add code to initialize timer_1 for continuous interrupts every 100 ms (10 interrupts per second); the clock frequency is 50 MHz.

• Add code to initialize the CPU for interrupts with index 10.

• Add code to allow interrupts in general.

Interrupt code is the most difficult kind of code to debug, so make sure that all your code is easy to read. For every section of code you add or change, write detailed comments describing what you want to do, and how your code does it.

HA1.7. Test the program using the NIISim simulator. Remember to open the UART0 console window. Typical output from a short run can look like this:


The NIISim simulator can simulate the board hardware. Click View – I/O Board to open this view.

The seven-segment LEDs will update and look something like this (when showing 8888 0002):

Demonstration for Assignment 1 - Prime Time

There is no demonstration for Home Assignment 1 specifically. Home Assignments 1 through 5 are demonstrated together.


Home Assignment 2 – Exceptional Exclamation

Task

HA2.1. Create a new project in the Nios II IDE, and call the new project nios2int2. Re-use your Board Support Package from Home Assignment 1:

Re-using the Board Support Package will save you some disk space, and some compile time.

HA2.2. Use the Nios II IDE to copy all files from your Home Assignment 1 to the new project folder.

HA2.3. In the new project, change the filename of nios2int1main.s to nios2int2main.s.

Using the nios2int2 project, edit nios2int2main.s as follows. Use existing comments to guide your placement of the code sections you write. Add comments detailing how your own code works.

HA2.4. Modify the exception handler exchand. Add code to distinguish between interrupts and traps. For every piece of code you add or change, write detailed comments describing what you want to do, and how your code does it.


HA2.5. Modify the main program in nios2int2main.s, by inserting code near the label mainloop as specified below.

Original code:

mainloop: call primesearch # Add code here for Assignment 2 mov r4,r2 ## This is the end of the main loop.# We jump back to the beginning.br mainloop

Changed code, new instructions in red:

mainloop:call primesearchPUSH r4movi r4,33 # 33 = '!'trapPOP r4mov r4,r2## This is the end of the main loop.# We jump back to the beginning.br mainloop

The new program uses a trap instruction to print an extra character to the console (or terminal-emulator).

You MUST follow the specification.

HA2.6. Test the program using the NIISim simulator. Typical output from a five-minute run can look like this:

Note the exclamation sign ("!") after each prime-number printout.

Demonstration for Assignment 2 – Exceptional Exclamation



Home Assignment 3 – T-Time

Task

HA3.1. Create a new project in the Nios II IDE, and call the new project nios2int3. Re-use the Board Support Package you created for Home Assignment 1.

HA3.2. Copy all source files from your Home Assignment 2 to the new project folder. Change the filename of nios2int2main.s to nios2int3main.s.

HA3.3. Edit nios2int3main.s as follows. Modify the exception handler exchand, by inserting code near the label timer1int as specified below.

Original code:

# Before calling a subroutine, push r1 through r15, and r31. PUSHMOST

movia r4,mytime call puttime movia r4,mytime call tick # Add code here for Assignment 3 POPMOST # Afterwards, restore saved register values.

Changed code, new instructions in red:

# Before calling a subroutine, push r1 through r15, and r31.PUSHMOSTmovia r4,mytimecall puttimemovia r4,mytimecall tick

(you will need to add some code of your own here)

movi r4,'T'trap

(you will need to add some code of your own here)

POPMOST# Afterwards, restore saved register values.


The result should be that a T is printed after each time-display. However, since the trap instruction is now used from within an interrupt handler, that interrupt handler will need some additional modifications for this to work.

This situation is similar to the case when an interrupt handler can be interrupted. However, there is no need to re-enable interrupts, as the trap instruction is not affected by the Processor Interrupt-Enable (PIE) flag.

HA3.4. Edit nios2int3main.s, and perform the additional modifications necessary to allow the trap instruction to be used from within an interrupt handler. For every piece of code you add or change, write detailed comments describing what you want to do, and how your code does it.



HA3.5. Test the program using the NIISim simulator. Typical output may look like this:

Note the "T" after each time-printout.

Demonstration for Assignment 3 – T-Time


Home Assignment 4 – The Key

For this Home Assignment, you can use the NIISim simulator. to test your program.

Task


HA4.2. Copy all source files from your Home Assignment 3 to the new project folder. Change the filename of nios2int3main.s to nios2int4main.s.

HA4.3. Edit nios2int4main.s. Use the existing comments to guide your placement of the various code sections you write. For every piece of code you add or change, write detailed comments describing what you want to do, and how your code does it. The following modifications are required:

• Add code below the label main: (see the comments in the file) to initialize de2_pio_keys4 for interrupts when button KEY0 is pushed or released.

• Also add code to initialize the processor for interrupts with index 2, in addition to the previously initialized index 10.

• Add code in the exception handler exchand, to check if the interrupt came from timer_1 or from de2_pio_keys4.

• Also add code in the interrupt handler to perform the actions described in the table below, when an interrupt comes from de2_pio_keys4.


Action table for Assignment 4:

Input Action

Key KEY0 is pressed. (Down)

An upper-case 'D' is sent using the subroutine out_char_uart_0.

Key KEY0 is released. (Up)An upper-case 'U' is sent using the subroutine out_char_uart_0.

Hint: you can check the status of the actual button in the interrupt handler. The interrupt will be processed immediately after the button is pushed or released, so the button will not have time to move. Therefore, if the button is up, the interrupt must have happened because the button was released and not pushed, and vice versa.

HA4.4. Run your program in the NIISim simulator. Typical output will be identical to that of the previous Assignment. Test your program by clicking on the keys.

Laboratory Assignment 4 – The Key

LA4.1. Change the initialization value for Timer 1, so that the time-out period becomes exactly 1 second.

LA4.2. Follow our tutorial for connecting the DE2 board. Since you have finished lab 1 (nios2time), the driver is already installed.

LA4.3. Connect a serial cable between the DE2 board and a computer. We recommend that you use the computer supplied by KTH for this, even if you have your own computer with programs and Nios II Software. Use our USB-to-serial adapter if necessary. If you use the USB-to-serial adapter, start the terminal emulator putty according to the instructions for lab nios2io.

If you use a USB-to-serial converter, output will be visible only in the terminal emulator. The Nios II IDE may show a blank console window, or an error message. See the section on Known issues (above).

If your computer has a serial port, the Nios II IDE will detect the port and connect it to the console window. This is different from lab nios2io. The reason is that you selected uart_0 rather than the JTAG UART in the System Library settings for the current lab (nios2int).

LA4.4. Test your program using the DE2 board. Verify the following properties.

• Prime numbers must be printed several times per minute. • The time must be printed exactly once per second. The time will also be shown on the

seven-segment display. • A 'D' (for "down") must be printed when KEY0 is pressed, and an 'U' (for "up") must be

printed when the key is released.

Demonstration for Assignment 4 – The Key

Call the laboratory teacher, restart your program, and let him/her test it. Answer all questions he/she may ask.


Laboratory Assignment 5 – First Surprise Assignment

LA5.1. Use the Nios II IDE to create a new project, called nios2surprise1. If this is not your first surprise assignment, use the next available higher number: nios2surprise2, etcetera.

LA5.2. Use the Nios II IDE to copy all files from your nios2int4 project to the new project.

LA5.3. Contact the laboratory teacher; he/she will decide on an individual surprise assignment for you. The laboratory teacher's decision is not negotiable. You must complete your individual surprise assignment during the session, in order to pass this laboratory exercise.Before making the decision, the laboratory teacher will welcome suggestions from you, for surprise projects that you find interesting. You can discuss projects of any difficulty, since projects which are too difficult (or too easy) will be rejected by the laboratory teacher.Surprise Assignments cannot be taken home to be shown later, but must be finished during the current session. Should you be unable to finish the Surprise Assignment, you will have to return for a later lab session. In that later session, you will get a new Surprise Assignment, to be finished during that session.

Demonstration for Assignment 5 – First Surprise Assignment

Show your completed surprise-project to the laboratory teacher. Answer all questions that he/she asks.

C-code Assignments

For assignment 6 and on, please use the files in the zipped archive called nios2int2014c.zip.

Assignments 6 and on use the Altera-supplied exception-wrapper. There's a short description on page 13. For more information on alt_ic_isr_register and other useful functions, please check Altera's literature. Each function is described in detail in the Nios II Software Developer's Handbook, Chapter 14 (HAL API Reference).

For these assignments, you will need our initialization fixup subroutine. The subroutine is called intfix and is available in file intfix.c. The intfix subroutine must be called before any other code in your program, and only once.

The intfix subroutine removes all unused handlers (which have been added by Altera-supplied initialization code). After running intfix, interrupts are enabled only from the JTAG UART, and also from the system timer (timer_0). These devices are used by the Altera-supplied system software for communication between the DE2 board and the Nios II IDE.

Detailed information: The Altera-supplied initialization code initializes all devices present in the system-design configuration file, and sets up standardized Interrups Service Routines for those devices. In our programs, we need to initialize some devices using our own code. Such devices include timer_1 and de2_pio_keys4. We also want to leave many devices uninitialized, and with interrupts turned off; those devices include timer_2 and others which are not used in this course. Calling alt_ic_isr_register, with a null-pointer argument for the interrupt-handling function, will remove the interrupt handler. The intfix subroutine calls alt_ic_isr_register in this way, once for each unwanted interrupt handler.


Home Assignment 6 – Toggles

For this Home Assignment, you can use the NIISim Simulator to test some parts of your program. The parallel input-port de2_pio_keys4, and the buttons that provide input through that port, are not simulated. At the laboratory session, you will be able to test the complete program by running it on a DE2 board.

To get you started, we provide the file nios2intc.c (also available in a zipped archive).

You will also need an initialization fixup subroutine, intfix.c), for Home Assignment 6 and on. The intfix subroutine must be called before any other code in your main program, and only once. The intfix subroutine disables the Altera-supplied interrupt handlers for most devices.

Task preliminaries - do this first!


HA6.2. Copy files intfix.c, nios2intc.c and puttime_uart_0.c to the project folder. Also copy the source file for the tick.c subroutine to the new project folder. If necessary, right-click the project name and select Refresh, so that the Nios II IDE re-checks the contents of the project directory.

The supplied file nios2intc.c initializes interrupts from the push-button KEY0, connected to the de2_pio_keys4 device. The interrupt handler is called irq_handler_keys, and performs the actions specified in the table below. Make sure you understand how the interrupts from the de2_pio_keys4 device works, and how they are initialized.

Action table for interrupts from de2_pio_keys4

Input Action

Key KEY0 is pressed.

An upper-case 'D' is printed using out_char_uart_0. Green LED LEDG0 lights up (and continues shining).The handler waits about 2 seconds, after which time a lower-case 'd' is printed using out_char_uart_0.

Key KEY0 is released.An upper-case 'U' is printed using out_char_uart_0.Green LED LEDG0 turns off (and continues being dark).

One or several out of KEY1 through KEY3 are pressed and/or released.

Nothing happens.

The supplied file nios2intc.c contains a C-language interrupt-handler for de2_pio_keys4. This handler implements actions very similar to those of your assembly-language interrupt handler from Assignment 5. Differences:

• The C-language handler turns on green LED LEDG0 for the button-down interrupt, and turns off the same LED for the button-up interrupt. The assembly-language handler does not affect the green LEDs.

• The C-language handler delays for about 2 seconds before returning. There is no such delay in the assembly-language handler.

• The C-language handler prints a lower-case 'd' after the delay but immediately before returning. The assembly-language handler only prints uppercase letters 'D' and 'U' (see action tables for details).


Task - the real tasks are here!

HA6.3. Write new subroutines toggles_init and irq_handler_toggles; toggles_init initializes the parallel input-port de2_pio_toggles18 for interrupts, while irq_handler_toggles examines which switch (or switches) has (or have) been toggled, and performs actions detailed below. Modify your main program to contain calls to these functions. Test the subroutines using the main program.

We recommend that you add the subroutines toggles_init and irq_handler_toggles to the main program file (nios2intc.c).

Note: Having one large file with most of the code is not the best practice in general, but can be accepted for small programs. The best practice is to have separate files for separate functions. This, however, would require you to add correct C function headers (type definitions) to all files, or to write a separate header file. The added complexity would be beyond the scope of this laboratory exercise.

Specification: toggles_init

Name: The subroutine must be called toggles_init.Input parameters: None.Return value: None.Side effects: The subroutine must initialize the parallel input-port de2_pio_toggles18, controlled by reading and writing addresses in the range 0x850-0x85F, so that its interrupt output is activated when switch SW0 changes position ("toggles"). The subroutine must also "register the ISR" by calling the alt_ic_isr_register function with correct input parameters..The values in registers r1 through r15 may be altered. All other registers must have unchanged values when the subroutine returns.Language: You must use the C language for this subroutine.C language: The C-language function prototype is:void toggles_init( void );

Specification: irq_handler_toggles

Name: The subroutine must be called irq_handler_toggles.Input parameter: Only one: a pointer to a context (first parameter, in register r4). The subroutine is allowed to ignore both parameters.Return value: None.Side effects: In all cases, the interrupt must be acknowledged. Furthermore, actions should be taken according to the table below.The values in registers r1 through r15 may be altered. All other registers must have unchanged values when the subroutine returns.Language: You must use the C language for this subroutine.C language: The C-language function prototype is:void irq_handler_toggles( void * );


Action table for interrupts from de2_pio_toggles18

Input Action

Switch SW0 changes position.

Red LED LEDR0 lights up, and an upper-case 'S' is printed using out_char_uart_0.The interrupt handler then waits for a predefined time by calling bigdelay();After the wait, red LED LEDR0 turns off (and continues being dark), and a lower-case 's' i printed using out_char_uart_0.

One of SW1 through SW17 changes position.

Nothing happens.

You MUST follow the specifications.

HA6.5. Compile the project, and test the program using the NIISim simulator. Typical output may look like this:

HA6.6. Test button KEY0 with the NIISim simulator and check the LEDs, and the changes in the UART0 console output. When pressing and holding KEY0, you should see a D, then a pause, then a d. When releasing KEY0, you should see an U.


Laboratory Assignment 6 – Toggles

LA6.1. Modify the definition of TIMER_1_TIMEOUT in the file nios2intc.c, so that the larger value is used (49999999). Otherwise, your display will be cluttered with time values, and hard to read. Rebuild the project.

Note: When using the DE2 hardware, all output from the DE2 board will use uart_0. Remember to connect the serial cable. If you use a USB-to-serial converter, output will be visible only in the putty terminal-emulator.

LA6.2. Test your program using the DE2 board. Verify that keypresses and switch-toggling cause actions according to the action tables. Also check that underscores are still printed several times per second, and that the time is printed correctly once per second.

Examine specifically what happens in the following cases. Make sure you can explain the behavior.

LA6.3.Press button KEY0 and hold it down. Move switch SW0 from one position from the other. Immediately after this, while the handler irq_handler_toggles is still waiting, release KEY0. Explain the printouts on the console, and the behavior observed on the red and green LEDs.

LA6.4. Toggle switch SW0. Immediately after this, while the handler irq_handler_toggles is still waiting, press button KEY0 and release it again immediately. Explain the printouts on the console, and the behavior observed on the red and green LEDs.

Demonstration for Assignment 6 – Toggles

Call the laboratory teacher, restart your program, and let him/her test it. Answer all questions he/she may ask. Explain the behaviors in Laboratory Assignments LA6.3 and LA6.4.

Laboratory Assignment 7 – Second Surprise Assignment

Note: there is no Home Assignment 7.

LA7.1. Use the Nios II IDE to create a new project, called nios2surprise1. If this is not your first surprise assignment, use the next available higher number: nios2surprise2, etcetera.

LA7.2. Use the Nios II IDE to copy all files from your nios2int7 project to the new project.

LA7.3. Contact the laboratory teacher; he/she will decide on an individual surprise assignment for you. The laboratory teacher's decision is not negotiable. You must complete your individual surprise assignment during the session, in order to pass this laboratory exercise.Before making the decision, the laboratory teacher will welcome suggestions from you, for surprise projects that you find interesting. You can discuss projects of any difficulty, since projects which are too difficult (or too easy) will be rejected by the laboratory teacher.Surprise Assignments cannot be taken home to be shown later, but must be finished during the current session. Should you be unable to finish the Surprise Assignment, you will have to return for a later lab session. In that later session, you will get a new Surprise Assignment, to be finished during that session.

Demonstration for Assignment 7 – Second Surprise Assignment

Show your completed surprise-project to the laboratory teacher. Answer all questions that he/she asks.


Laboratory Assignment 8 – Packing up the Board

Please make sure that box and board matches

The number on the board should match the number on the box. If the numbers don't match, please find the right box.

In case you fail to find the correct box, talk to the laboratory teacher, so that he/she can make a note (and match up the boards and boxes later).

Power supply and USB cable, nothing else

The USB cable and power supply should be at the bottom of the box. Let the cables lie loosely - they may not fit otherwise.

At some laboratory sessions, you will use extra cables. Any extra cables should not be in the box. Please give them to the laboratory teacher, who will pack them separately.


Cardboard divider

Now fold in the cardboard divider.

Plastic-foam protector and the DE2 board

After you have folded in the divider, put in the plastic-foam protector and place the board in the foam.

One edge of the plastic foam has a cut-out for the connectors that extend slightly from the back of the board. Please orient the board so that the connectors face this cut-out area. Otherwise, the board will not fit well into the plastic foam.


Foam sheet on top

Now add the thin sheet of foam, to protect the top of the board.

Note: Some boxes do not have a foam-sheet.

Close the box and return it

Finally, close the box, and return it to the laboratory teacher.

Taking good care of our laboratory boards make them last longer. Thank you for your help!


Error messages

Every error and every warning must always be fixed. Zero errors, zero warnings is a requirement for passing the laboratory exercise.

• Errors exist in a required project. Continue launch?Always click "No". Fix all errors and all warnings before continuing.

• Warning: end of file not at end of a line; newline inserted, orWarning: end of file in comment; newline insertedIf your program behaves like no program should, perhaps you ignored this warning?There must be an empty line at the end of every source file. An assembly-language file without the empty line at the end will not be correctly compiled; the last line will be ignored. To fix, press: Ctrl-End, Enter, Home, Delete, Delete. Pressing Home, Delete, Delete removes the whitespace characters that are usually auto-inserted by the editor when you create a blank line.

• In function `alt_main': undefined reference to `main'Every project must have exactly one function or label called main. In case main is a label in assembly-language, check that you have a (correctly spelled) directive .global main A project can never have two or more files with a main function or label. If your project has, the project cannot compile successfully. Please double-check our instructions to find the step that went wrong.

• make: *** No rule to make targetThis can happen if there is whitespace in the path to your workspace. Check this. To fix, re-do the First Project. You can copy files from the old (incorrect) workspace-folder afterwards.

• No valid design files foundRight-click the project name, select Refresh. If compilation fails again after this, check the file-tree shown by the Nios II IDE. Make sure that you really did write some code, and that you saved that code in one or more files inside the project directory. If all else fails, create a new project, copy your files there, and continue.

• The pipe is being closed.This is one of the many possible error messages that cen be seen when a folder containing Nios II program code has been copied, moved, renamed or transferred to a different computer. To fix, create a new project, copy your files there, and continue.

• There are no JTAG cables available on your system.Often requires restarting your computer.

• Confirm Perspective Switch - This kind of launch is configured to open the Debug perspective when it suspends. - Do you want to open this perspective now?This is normal. In this case, you can check "Remember my decision" and click "Yes".

• nios2-terminal: can't open uart: Permission deniedFor nios2time (this laboratory exercise), restart your computer. For nios2io and niosint, this message is normal.

• No HardwareCheck the connection between the board and the PC running the Nios II Software, and that you have downloaded the Nios II system into the board (file DE2_N2_20090707.sof). Make


sure that the computer end of the cable really is connected to the computer. Some desktop systems may have USB connectors on the screen, but no USB connection from screen to computer.

• [Target Connection]: No Nios II target connection paths were locatedFirst check the hardware: is your board powered on, and do you use the "BLASTER" connector (and not the other one)?Now check the firmware: have you downloaded our Nios II processor SOF-file using Quartus II programmer, after powering-up the board? The board forgets the Nios II processor completely, every time power is removed.If all of the above are OK, you have encountered a known bug. The work-around is usually a three-step process. Step 1. A dialog box will have popped up. Select the tab "Target Connection", and make sure the boxes "ignore mismatched system ID" and "ignore mismatched system timestamp" are checked. Then click "Refresh connections". Click "Apply", unless that button is greyed-out (because no settings were changed). Now click "Run", unless that button is greyed-out (because the Nios II Software Build Tools has not managed to connect successfully to the DE2 board).Sometimes this works, and you're done!Step 2 (if necessary). Close Eclipse. This takes a few seconds – wait it out. On Windows, restart the Nios II Software Build Tools and try again.On Linux, repeat the command eclipse-nios2 to re-start it. After a few seconds, check the command-line terminal window you used to start Eclipse. Look for "Discovered connected devices". If you only see "Discovered connected devices" and nothing else, close and re-start Eclipse again. Should this happens more than three times in a row, call the laboratory teacher.You want to see something like the following:Discovered connected devices: Processor: nios2_0 Path: /connections/USB-Blaster on localhost (3-1)/EP2C35@1/(70:34 v2 #0)/nios2_0 Byte Stream Device: jtaguart_0 Path: /connections/USB-Blaster on localhost (3-1)/EP2C35@1/(110:128 v1 #0)/jtaguart_0When you see something like this in the terminal, try "Run As – Nios II Hardware" again.Sometimes this works, and you're done!Step 3 (if necessary). You may see a long message in red letters scroll by in the console window. The message disappears, and a pop-up window saying "Downloading ELF process failed" is shown. Close the pop-up. Your project has now gone "bad". Create a new project, and copy all files from the "bad" project to the new project. Note: copy the files, don't cut-and-paste them. Build and run the new project. This time, it will work.

Version history for this document

2014-11-06: Initial version for Fall, 2014.

2014-08-28: Working version for Fall, 2014.


Documents

IS1200/IS1500 Computer Engineering - KTHIS1200/IS1500 Computer Engineering Laboratory Exercise nios2int – Interrupts and Traps ... code, use a flow-chart to explain what happens