# Machine10 x86-64 guest ABI v1

Contract: public v1. The retained profile identifies its shared descriptor as
ABI numeric version 3 and its event as numeric version 2. Use those exact
numbers when implementing this contract version.

## Execution model

Each turn starts a fresh x86-64 VM at guest physical address `0x100000` in
64-bit mode. The guest has no firmware, operating system, libc, filesystem,
network stack, clock device, or ambient credentials. It receives one event,
may call explicitly granted JMPKit resources, commits or fails, and exits.

Initial registers:

| Register | Value |
|---|---|
| `RIP` | `0x00100000`, program entry |
| `RSP` | `0x001f0000` |
| `RDI` | event descriptor address |
| `RSI` | event descriptor size |
| `RDX` | response buffer address |
| `RCX` | response buffer capacity |
| `R8` | shared Machine ABI descriptor address |

All integers and structures are little-endian. Include either
`include/machine10-main.inc` or `include/machine10-main.h` rather than copying
numeric offsets into each program.

## Event

The event descriptor identifies `init`, `timer`, or `trigger`, the stable
occurrence sequence, prior committed generation, and a bounded JSON payload.
The payload pointer and length are valid only during the turn.

The app-facing `kind` remains in the JSON payload and durable Machine record.
At the guest boundary, every non-init/non-timer occurrence uses the `trigger`
event type.

## Retained memory

Guest physical addresses `0x02000000` through `0x03ffffff` form a 32 MiB
logical retained aperture. It is zero on the first `init` turn. Pages changed
and committed by a successful turn are restored for the next turn. Untouched
pages remain zero and consume no persisted page record.

The guest should validate its own state version and the event's prior
generation before changing retained data. A failed turn publishes neither its
memory nor its response.

## Doorbell operations

Write a 32-bit operation to I/O port `0x4d10`:

- `M10_OP_HTTP_CALL`: perform the request described in the shared ABI and
  return status/body or a Machine error.
- `M10_OP_COMMIT_SLEEP`: atomically commit memory/output/timer instruction and
  leave the Machine available for later work.
- `M10_OP_COMMIT_STOP`: commit and enter the stopped lifecycle.
- `M10_OP_EXIT`: fail the turn without committing a successor generation.

After a terminal operation, execute `cli; hlt`. Do not continue executing.

## Motherboard call

Before `M10_OP_HTTP_CALL`, fill method, unique request ID, target address and
length, optional body address and length, response address/capacity, and clear
response length, status, and error. After the call returns:

- `error == M10_ERROR_NONE` means `http_status` and `response_length` are
  valid;
- `completion_sequence` advances once per completed call; and
- response bytes occupy the supplied bounded response buffer.

The target is an app-relative ASCII HTTP path accepted by the capability
contract. The guest cannot add bearer or authority headers. Current request
bodies and resource responses are bounded to 64 KiB, targets to 1024 accepted
characters, and calls to the installed `maxCalls` value.

## Commit

Before commit, set:

- response bytes, length, and an application status where useful;
- timer action: keep, cancel, or set with `wake_after_ms`;
- disposition: sleep or stop; and
- `error = M10_ERROR_NONE`.

The host validates every pointer, length, operation, state generation, timer,
snapshot, and response before publishing. Treat all private snapshot and
runner transport formats as opaque.

## Run Now profile

Run Now uses the smaller definitions in `include/machine10-run.inc`. `RDI` and
`RSI` point directly to a JSON `machine10.http-request.lab.v1` event. It uses
`M10_OP_RESPOND` rather than retained commit and has no retained aperture or
timer lifecycle. See `machine10-run-now-v1.md` and `examples/run-now-q.S`.