# A subroutine with its arguments in registers

[Courses](https://asm-editor.specy.app/learn/courses.md) › [x86-64 assembly](https://asm-editor.specy.app/learn/courses/x86.md) › Examples

Web page: https://asm-editor.specy.app/learn/courses/x86/examples/subroutine-with-register-arguments

> Pass arguments in rdi and rsi and return a result in rax using the System V calling convention. Follow the return address on the stack through call and ret.

The same program in: [M68K](https://asm-editor.specy.app/learn/courses/m68k/examples/subroutine-with-register-arguments.md), [MIPS](https://asm-editor.specy.app/learn/courses/mips/examples/subroutine-with-register-arguments.md), [RISC-V](https://asm-editor.specy.app/learn/courses/risc-v/examples/subroutine-with-register-arguments.md), [Z80](https://asm-editor.specy.app/learn/courses/z80/examples/subroutine-with-register-arguments.md)

Suppose a program needs to add two numbers and then continue with the answer. Here `_start` gives
20 and 22 to `sum`. The subroutine adds them and returns 42. The caller saves that answer in
`r12`, where you can inspect it after the exit setup changes `rax`.

```x86
default rel
global _start

section .text
; sum(a, b) -> a + b
; The System V convention puts the first two arguments in rdi and rsi
; and expects the return value in rax.
sum:
    mov rax, rdi            ; start the answer with a
    add rax, rsi            ; add b
    ret

_start:
    mov rdi, 20             ; first integer argument
    mov rsi, 22             ; second integer argument
    call sum
    mov r12, rax            ; execution resumes here; r12 = 42

    mov rax, 60             ; syscall 60: exit
    xor rdi, rdi
    syscall
```

Under the System V calling convention, the caller puts the first two integer arguments in `rdi`
and `rsi`, and the subroutine returns an integer in `rax`. `sum` follows that agreement.
The `call` and `ret` instructions let execution return to the instruction after the call.

## Follow the return address

Choose **Open in editor**, then step through the program while watching `rip` and `rsp` in the
register panel. To inspect the stack, enter the current value of `rsp` in the memory panel's
address box. `rip` tells you which instruction will execute next. Let `S` stand for the value of
`rsp` just before `call sum`; your run will show a concrete address instead.

| When you stop          | `rip` points to         | `rsp`   | What to inspect                                           |
| ---------------------- | ----------------------- | ------- | --------------------------------------------------------- |
| Before `call sum`      | `call sum`              | `S`     | The caller is about to leave `_start`.                    |
| After executing `call` | `mov rax, rdi` at `sum` | `S - 8` | The qword at `[rsp]` holds the address of `mov r12, rax`. |
| Just before `ret`      | `ret` at `sum`          | `S - 8` | The same address is still at `[rsp]`; `rax` now holds 42. |
| After executing `ret`  | `mov r12, rax`          | `S`     | The caller has resumed immediately after its `call`.      |

This 64-bit `call` stores an eight-byte return address: one qword.
It first subtracts 8 from `rsp`, writes the address of the instruction following the `call` at
the new `[rsp]`, and sets `rip` to `sum`. `ret` reads that qword into `rip` and adds 8 to `rsp`.
The old bytes may still be visible in memory afterward, but that stack slot is no longer in use.

This is why a subroutine must leave `rsp` pointing at its return address when it reaches `ret`.
If `sum` pushed another value without popping it, `ret` would read that value as an address and
try to continue there.

`sum` changes only `rax`, which is a caller-saved register. If a subroutine uses a callee-saved
register such as `rbx` or `r12`, it must restore the caller's value before returning. The
caller can use `r12` here to keep the result after `sum` returns.

## Your turn

Write `difference(a, b)` so it reads `a` from `rdi`, reads `b` from `rsi`, and returns `a - b`
in `rax`. In `_start`, call it with 50 and 8, then save the result in `r12`. Call the same
subroutine again with 100 and 37, and save that result in `r13`. Write the argument setup and
both calls yourself.

Before running, predict both answers. Then press **Test**: it expects `r12 = 42` and `r13 = 63`.
You can also step through both calls. Each `call` puts a different return address at `[rsp]`:
the first leads to `mov r12, rax`, and the second leads to `mov r13, rax`. After each `ret`,
`rsp` is back where it was before that call.

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

```x86
default rel
global _start

section .text
; difference(a, b) -> a - b
difference:
    ; Write the two instructions that put a - b in rax.
    ret

_start:
    ; Call difference(50, 8), then save its answer in r12.

    ; Call difference(100, 37), then save its answer in r13.

    mov rax, 60
    xor rdi, rdi
    syscall
```

*Testcase for the program above (JSON):*

```json
{
    "expectedRegisters": {
        "r12": 42,
        "r13": 63
    }
}
```

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

*Solution:*

```x86
default rel
global _start

section .text
; difference(a, b) -> a - b
difference:
    mov rax, rdi
    sub rax, rsi
    ret

_start:
    mov rdi, 50
    mov rsi, 8
    call difference
    mov r12, rax

    mov rdi, 100
    mov rsi, 37
    call difference
    mov r13, rax

    mov rax, 60
    xor rdi, rdi
    syscall
```

</details>

## Instructions in this Lecture

- x86-64: [`mov`](https://asm-editor.specy.app/documentation/x86/instruction/mov.md), [`add`](https://asm-editor.specy.app/documentation/x86/instruction/add.md), [`ret`](https://asm-editor.specy.app/documentation/x86/instruction/ret.md), [`call`](https://asm-editor.specy.app/documentation/x86/instruction/call.md), [`xor`](https://asm-editor.specy.app/documentation/x86/instruction/xor.md), [`syscall`](https://asm-editor.specy.app/documentation/x86/instruction/syscall.md), [`sub`](https://asm-editor.specy.app/documentation/x86/instruction/sub.md)

Previous: [Even or odd, count the set bits, multiply by shifting](https://asm-editor.specy.app/learn/courses/x86/examples/bit-tricks.md)

Next: [Stack arguments and a stack frame](https://asm-editor.specy.app/learn/courses/x86/examples/subroutine-with-stack-arguments.md)
