# When an instruction cannot be carried out

[Courses](https://asm-editor.specy.app/learn/courses.md) › [RISC-V assembly](https://asm-editor.specy.app/learn/courses/risc-v.md) › Talking to the outside world

Web page: https://asm-editor.specy.app/learn/courses/risc-v/talking-to-the-outside-world/exceptions

> Install an exception handler, read the details of a misaligned load, and use uepc and uret to resume after it.

Overview of this topic: [Assembly basics](https://asm-editor.specy.app/learn/courses/assembly-basics/talking-to-the-outside-world/interrupts-and-exceptions.md)

The same topic in: [M68K](https://asm-editor.specy.app/learn/courses/m68k/talking-to-the-outside-world/exceptions-and-the-vector-table.md), [MIPS](https://asm-editor.specy.app/learn/courses/mips/talking-to-the-outside-world/exceptions-and-coprocessor-0.md), [Z80](https://asm-editor.specy.app/learn/courses/z80/talking-to-the-outside-world/interrupts-im-ei-di-and-halt.md), [x86-64](https://asm-editor.specy.app/learn/courses/x86/talking-to-the-outside-world/interrupts-exceptions-and-signals.md)

`ecall` is a deliberate trap: your program runs it to ask the Playground to do something. This
lesson handles a different kind of event, a **synchronous fault**: an instruction cannot be carried
out, so the processor transfers control to a handler.

For example, `lw` needs a word-aligned address. An address ending in binary `...01` is not a
multiple of four, so a word load from it faults.

## What happens on a fault

Before the handler's first instruction, the hardware does these things in order:

1. It abandons the instruction that cannot run.
2. It writes that instruction's address to **`uepc`**.
3. It writes a cause code to **`ucause`**, and the related address or value to **`utval`**.
4. It jumps to the address in **`utvec`**, if user exceptions are enabled in **`ustatus`**.

The handler finishes with **`uret`**. `uret` resumes execution at the address currently in `uepc`.
That is why a handler can either retry a faulting instruction or arrange to skip it.

`utvec`, `ustatus`, `uepc`, `ucause`, and `utval` are control and status registers (CSRs), separate
from the 32 general-purpose registers. These are the CSR instruction forms used here:

| instruction       | meaning                                        |
| ----------------- | ---------------------------------------------- |
| `csrr rd, csr`    | read a CSR into general-purpose register `rd`  |
| `csrw rs, csr`    | write general-purpose register `rs` into a CSR |
| `csrsi csr, mask` | OR the immediate mask into a CSR               |

So `csrsi ustatus, 1` ORs in the mask `1` (`...0001` in binary), setting bit 0. Without enabling
bit 0, writing a handler address to `utvec` alone has no effect. When user exceptions are disabled,
this Playground reports the fault and ends the run.

## Installing a handler

This program deliberately places `w` at a misaligned address. The variable `odd` occupies one byte.
`.align 0` prevents the usual padding before the word, so `w`'s address ends in `...01`. A normal
word alignment directive would insert padding before `w`.

The handler uses `t0` and `t1`, so it saves and restores both. It makes two word-sized stack slots,
saves those registers, does its work, restores them, then restores `sp`. The Playground provides a
valid stack for this program, and every stack access below is word-aligned.

```riscv
.data
odd:        .byte 1
            .align 0
w:          .word 0x12345678
            .align 2
last_cause: .word 0
last_value: .word 0

.text
.globl main
main:
    la t0, handler
    csrw t0, utvec              # source register first, CSR second
    csrsi ustatus, 1            # OR in mask 1: enable bit 0

    la t1, w                    # w ends in ...01 because padding was disabled
    lw t2, 0(t1)                # misaligned load: enter handler
    li s0, 5                    # runs after the handler returns
    j end                       # do not fall through into handler

handler:
    addi sp, sp, -8             # make two aligned words on the stack
    sw t0, 0(sp)
    sw t1, 4(sp)                # preserve both registers this handler will use

    csrr t0, ucause
    la t1, last_cause
    sw t0, 0(t1)                # record why the fault happened
    csrr t0, utval
    la t1, last_value
    sw t0, 0(t1)                # record the address involved

    csrr t0, uepc               # address of the faulting lw
    addi t0, t0, 4              # all instructions assembled here are 32-bit (4 bytes)
    csrw t0, uepc               # resume at the following instruction

    lw t1, 4(sp)
    lw t0, 0(sp)
    addi sp, sp, 8              # restore both registers and the original stack pointer
    uret

end:
```

Here `j end` is ordinary control flow. `end` names the address after the last assembled instruction,
so reaching it completes this Playground run.

After the run, `s0` is 5. `last_cause` holds 4, the code for a misaligned load, and `last_value`
holds the misaligned address of `w`.

## Choosing where to return

`uepc` contains the address of the `lw` that faulted, not the address after it. If the handler
executes `uret` without changing `uepc`, the processor retries that same `lw`; it faults again and
the program repeats the handler forever.

This handler chooses not to perform the load, so it adds 4 to `uepc`. Four is correct for the
32-bit, four-byte instructions this Playground assembles. A handler that repaired the problem
instead would leave `uepc` unchanged and let the instruction run again.

For these memory faults, `ucause` and `utval` help identify the problem:

| code | what happened            | `utval`                  |
| ---: | ------------------------ | ------------------------ |
|    4 | load address misaligned  | the load address         |
|    5 | load access fault        | the inaccessible address |
|    6 | store address misaligned | the store address        |
|    7 | store access fault       | the inaccessible address |

Arithmetic instructions do not raise these faults. As you saw in the arithmetic lesson, `div`
produces `-1` for division by zero in this Playground.

## Faults and interrupts

An interrupt is a device asking for attention between instructions; it is different from the
instruction-caused faults above. The same handler can receive timer and keyboard interrupts; see
[Interrupts and the timer](https://asm-editor.specy.app/documentation/risc-v/interrupts.md) for examples. You can also keep using
polling for input: read the ready status, then read a character when one is available.

## Your turn

The `lw` below faults. Fill the handler so it advances `uepc` past that `lw` and returns with
`uret`. Preserve `t0` and restore `sp` before returning.

*Exercise: the code to start from, checked by the testcase after it:*

```riscv
.data
odd: .byte 1
     .align 0
w:   .word 0x12345678

.text
.globl main
main:
    li sp, 0x7FFFEFFC
    la t0, handler
    csrw t0, utvec
    li t0, 0x13579BDF
    csrsi ustatus, 1
    la t1, w
    li t2, 0x2468ACE0
    lw t2, 0(t1)
    li s0, 5
    j end

handler:
    # your handler here

end:
```

*Testcase for the program above (JSON):*

```json
{
    "startingRegisters": { "sp": "0x7FFFEFFC" },
    "expectedRegisters": {
        "s0": 5,
        "t0": "0x13579BDF",
        "t2": "0x2468ACE0",
        "sp": "0x7FFFEFFC"
    }
}
```

The checks verify that execution reaches `li s0, 5` and that `t0`, `t2`, and `sp` keep their
original values. Step through your handler to check how it updates `uepc` and returns with `uret`.

<details>
<summary>Show solution</summary>

*Solution:*

```riscv
.data
odd: .byte 1
     .align 0
w:   .word 0x12345678

.text
.globl main
main:
    li sp, 0x7FFFEFFC
    la t0, handler
    csrw t0, utvec
    li t0, 0x13579BDF
    csrsi ustatus, 1
    la t1, w
    li t2, 0x2468ACE0
    lw t2, 0(t1)
    li s0, 5
    j end

handler:
    addi sp, sp, -4
    sw t0, 0(sp)
    csrr t0, uepc
    addi t0, t0, 4              # skip this four-byte lw
    csrw t0, uepc
    lw t0, 0(sp)
    addi sp, sp, 4
    uret

end:
```

</details>

## Instructions in this Lecture

- RISC-V: [`la`](https://asm-editor.specy.app/documentation/risc-v/instruction/la.md), [`csrw`](https://asm-editor.specy.app/documentation/risc-v/instruction/csrw.md), [`csrsi`](https://asm-editor.specy.app/documentation/risc-v/instruction/csrsi.md), [`lw`](https://asm-editor.specy.app/documentation/risc-v/instruction/lw.md), [`li`](https://asm-editor.specy.app/documentation/risc-v/instruction/li.md), [`j`](https://asm-editor.specy.app/documentation/risc-v/instruction/j.md), [`addi`](https://asm-editor.specy.app/documentation/risc-v/instruction/addi.md), [`sw`](https://asm-editor.specy.app/documentation/risc-v/instruction/sw.md), [`csrr`](https://asm-editor.specy.app/documentation/risc-v/instruction/csrr.md), [`uret`](https://asm-editor.specy.app/documentation/risc-v/instruction/uret.md)

Previous: [The bitmap display and the keyboard registers](https://asm-editor.specy.app/learn/courses/risc-v/talking-to-the-outside-world/the-bitmap-display-and-the-keyboard.md)

Next: [Moving values around](https://asm-editor.specy.app/learn/courses/risc-v/examples/moving-values.md)
