Add --clock-mhz: report emulated time from ReadEClock (issue #102)

[sidick]

Closes #102.

Adds --clock-mhz N, which makes ReadEClock report emulated time derived
from the CPU's emulated cycle count at the given clock rate, instead of host
wall-clock time. The motivation (from @codewiz in #102) is compiler A/B
benchmarking: host time measures how fast the host ran the emulation, not what
the guest would have cost, and the distortion is per-workload — 7x to 27x
across BenchWork — so it doesn't cancel out. With this flag the numbers become
reproducible and independent of host load.

How it works

Cpu::run for M68kCpu normally goes through m68k::CpuCore::run_batch,
whose BatchResult carries only instructions — there is no cycle count on
that path at all. When --clock-mhz is given, the run loop instead uses
run_for_cycles, which returns a real cycles total. That is the
transaction-exact path (set_precise_bus(true), one instruction at a time, no
trace JIT, no fast_mem), so it is deliberately the slowest mode volamos has.

ReadEClock's reported rate in D0 stays ECLOCK_PAL_HZ (709379)
regardless of --clock-mhz. Real Amigas derive the E-clock from chipset
timing, not the CPU clock, so the flag governs only the cycles-to-time
conversion feeding ev_hi/ev_lo. GetSysTime/TR_GETSYSTIME/DateStamp/
CurrentTime all stay on the host clock — a benchmark run shouldn't think
it's 1978.

The change is strictly additive: with the flag absent, run() takes the
existing run_batch path unchanged and read_eclock_handler runs the
identical host-clock arithmetic as before.

Refused combinations

Both are hard errors rather than warnings, because in each case the result
would be silently meaningless rather than merely degraded:

• --jit — run_batch never tracks a cycle count, so there is nothing to
  derive emulated time from. Not approximate: absent.
• --sanitize — run_via_cycles doesn't run the per-instruction
  shadow-map hooks, so the shadow call stack, return-address checks, below-SP
  tracking and violation-PC attribution would all be dead or stale. A
  sanitizer that reports clean because its checks didn't run is worse than one
  that refuses to start.

Measured cost

CoreMark 1.0 (coremark.amiga, --cpu 68020), host throughput, 3 runs
averaged per mode: --jit ~680 iter/s, --no-jit ~217, --clock-mhz 25 ~97.
So about 2.2x slower than --no-jit and 7x slower than --jit. For
replacing a 20-minute Copperline A/B with one command that's a rounding error,
but it does mean this wants to stay opt-in for benchmarking rather than
something the testsuite picks up.

Documented caveats

userdocs/CLI-Reference.md spells out four things that stay unrepresentative,
because each could otherwise produce a confidently wrong number:

1. No bus wait states. FlatMemory implements no sync and no bus
   timing, while Copperline bills real Chip/Fast RAM contention. Memory-bound
   code will improve enormously over host time but will not converge on real
   hardware.
2. Native library handlers are free. Time spent in volamos's Rust
   handlers costs zero emulated cycles, so a workload dominated by e.g.
   CopyMem reports an emulated time implying it spent none there.
3. Cpu::step doesn't accumulate. Guest code reached via step —
   RawDoFmt's PutChProc callouts, Supervisor routines — is invisible in
   the total.
4. Nested System()/Execute() gets a fresh counter, so bracketing a
   child process reads as ~zero elapsed time.

Testing

cargo test --workspace: 1035 passed, 0 failed. Build, clippy
(--all-targets) and fmt --check all clean.

New tests cover the cycle accounting, D0 staying at the PAL rate under the
new mode, a two-reading delta that genuinely discriminates cycle-derived from
wall-clock-derived timing, the default path being unaffected, both refused
combinations in both orders, and flag parsing including fractional, zero,
negative, NaN, inf, and out-of-range values.

The cycles-to-ticks arithmetic was verified independently against a
hand-built fixture at three clock rates (25 / 12.5 / 50 MHz), producing exact
predicted tick values with correct inverse-linear scaling.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EHvk3UiKvgnG2xb71UJ67R