# 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.

## CPU API

Fields:

mem(   Pointer to the memory area associated with this CPU
hook   Pointer to a word that is called after each instruction in :run and :runN

Methods:

run1 ( cpu -- )
  Run one instruction.

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

unhalt ( cpu -- )
  Unset the "halt" flag of the CPU.

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 ( 'unhalt 'halted? 'run1 mem( -- cpu )
  Allocates a new CPU struct with initial values. "hook" defaults to "drop".
