# CPU emulation common API

Most CPU emulators in Dusk OS follow a common API exposed by the CPU struct at
[emul/cpu.fs].

## Memory management

The CPU struct doesn't handle memory management itself, it simply receives a
pre-allocated memory address. The base CPU struct doesn't handle bounds either.

Thefore, one must be aware of the code it emulated to decide the proper size to
allocate for the emulated memory. Not allocating enough might result in emulated
code to corrupt host memory.

## API

### Struct

struct CPU
  field mem(
  method run1 ( cpu -- )
  method halted? ( cpu -- f )
endstruct

mem(   Pointer to the memory area associated with this CPU

run1 ( cpu -- )
  Unset the "halted" flag if needed, then run one instruction.

halted? ( cpu -- f )
  Yields whether the CPU is halted.

### Words

runN ( n cpu -- )
  Unhalts the CPU then run "n" instructions or until the CPU is halted.

run ( cpu -- )
  Unhalts the CPU and then run until the CPU is halted.

newcpu ( 'halted? 'run1 mem( -- cpu )
  Allocates a new CPU struct with initial values.
