# Phase 13 - Timer

## Context

A timer provides a predictable interrupt source. Operating systems need timers for
scheduling, timeouts, and delays.

## Goals

- Implement a free-running machine timer counter.
- Implement compare register behavior.
- Generate and handle timer interrupts through the trap path.

## New Concepts

- `mtime`: monotonically increasing machine timer counter.
- `mtimecmp`: compare value that triggers a timer interrupt when reached.
- Interrupt: asynchronous trap caused by external or timer event.
- Pending bit: CSR bit indicating an interrupt source is waiting.

## How To Think About It

Timer hardware is simple; correct interrupt integration is the real lesson. You must
coordinate compare logic, pending state, enable bits, global interrupt enable, and trap entry.

## Learning Tasks

- Draw how `mtime`, `mtimecmp`, `mip`, and `mie` relate.
- Decide how software reads/writes a 64-bit timer from a 32-bit core.
- Trace a timer interrupt from compare match to handler entry.

## Pitfalls

- Generating level interrupts that never clear.
- Mishandling 64-bit register access from RV32 software.
- Taking interrupts while already in an unsafe state.

## Tooling And Testing

- Simulate with small compare values so tests finish quickly.
- Test enabling, disabling, pending, and clearing behavior separately.
- Add waveform probes for `mtime`, compare result, pending bit, and trap entry.

## References

- RISC-V privileged architecture spec: https://riscv.org/technical/specifications/
- RISC-V ACLINT specification: https://github.com/riscvarchive/riscv-aclint
- Linux timekeeping background: https://docs.kernel.org/timers/