# gizlang/target

Raw target authority for freestanding programs. A machine operation is a `machine_` declaration: one with `@Asm` annotations is that inline assembly, the others' bodies the compiler writes. A hosted program cannot link these as runtime services.

```gizlang
import * as Target from "gizlang/target";
```

## Types

### `Asm`

```gizlang
type Asm = { cpu: string; code: string; constraints: string; }
```

The assembly of a machine operation on CPU (`x86_64`, `aarch64`, `riscv64`, `riscv32` or `xtensa`), in LLVM's
inline assembly: CODE names the result $0, when there is one, and the parameters after it in order (each a 64-bit
scalar: i64, u64 or f64), and CONSTRAINTS gives their registers and clobbers (`={rax},{rcx},~{rdx},~{memory}`). One annotation for
each CPU the operation has.

- `cpu`: `string`
- `code`: `string`
- `constraints`: `string`

### `Section`

```gizlang
type Section = { name: string; }
```

The linker section of a function or a module `let` (`@Section(".text.boot")`): letters, digits and `._$-`.

- `name`: `string`

### `Align`

```gizlang
type Align = { bytes: i64; }
```

The alignment in bytes of a function or a module `let` (`@Align(4096)`): a power of two up to 2^32.

- `bytes`: `i64`

### `ThreadLocal`

```gizlang
type ThreadLocal = {}
```

Each thread has its own copy of a static module `let` (`@ThreadLocal`), in a runtime package or a freestanding Linux
process: they have thread-local storage.

Opaque: create and use it through this module's functions.

### `Indirect`

```gizlang
type Indirect = {}
```

A C declaration that is the type of a C function pointer (`@Indirect`): its first parameter, a u64, is the function's
address, and each call goes there with the C types of the other parameters and the result. Wasm checks the type of each
indirect call, so a call through an address always names the exact type.

Opaque: create and use it through this module's functions.

### `Export`

```gizlang
type Export = { name: string; }
```

The C symbol of a function or a static module `let` of a freestanding image (`@Export("gizlang_block_alloc")`). A
function takes C's calling convention: C calls it with its own arguments, and a fault in it traps.

- `name`: `string`

### `PhysicalAddress`

```gizlang
type PhysicalAddress
```

A device/bus address, distinct from an address that the CPU can dereference. Mapping policy belongs to the OS.

Opaque: create and use it through this module's functions.

### `VirtualAddress`

```gizlang
type VirtualAddress<T>
```

A bounded, naturally aligned CPU view of fixed-layout T values. It does not own or keep the allocation alive.

Opaque: create and use it through this module's functions.

### `MmioRegion`

```gizlang
type MmioRegion<Device>
```

A device's mapped registers. Memory reads, writes and atomics cannot take this type.

Opaque: create and use it through this module's functions.

## Functions

### `physicalAddress`

```gizlang
function physicalAddress(value: u64): PhysicalAddress
```

The physical address VALUE.

### `physicalBits`

```gizlang
function physicalBits(value: PhysicalAddress): u64
```

The bits of the physical address VALUE.

### `virtualBits`

```gizlang
function virtualBits<T>(value: VirtualAddress<T>): i64
```

The CPU address of VALUE's first byte.

### `unsafeRegion`

```gizlang
function unsafeRegion<T>(base: i64, bytes: i64): VirtualAddress<T>
```

The caller establishes the mapping and its lifetime. All later projections check the bounds and alignment.

### `project`

```gizlang
function project<T, U>(region: VirtualAddress<T>, offset: i64): VirtualAddress<U>
```

A single U within REGION. Use offsetOf<T, U>("field") for a checked record field.

### `element`

```gizlang
function element<T>(region: VirtualAddress<T>, index: i64): VirtualAddress<T>
```

Element INDEX of a region of T values, with no unchecked index multiplication.

### `slice`

```gizlang
function slice<T>(region: VirtualAddress<T>, first: i64, count: i64): VirtualAddress<T>
```

COUNT complete T values beginning at FIRST.

### `bytes`

```gizlang
function bytes<T>(region: VirtualAddress<T>): i64
```

The size of REGION in bytes.

### `read8`

```gizlang
function read8(at: VirtualAddress<u8>): u64
```

Read the byte at AT, zero-extended.

Effects: fail, read.

### `read16`

```gizlang
function read16(at: VirtualAddress<u16>): u64
```

Read the 16 bits at AT, zero-extended.

Effects: fail, read.

### `read32`

```gizlang
function read32(at: VirtualAddress<u32>): u64
```

Read the 32 bits at AT, zero-extended.

Effects: fail, read.

### `read64`

```gizlang
function read64(at: VirtualAddress<u64>): u64
```

Read the 64 bits at AT.

Effects: fail, read.

### `write8`

```gizlang
function write8(at: VirtualAddress<u8>, value: u64): void
```

Write the byte VALUE at AT. VALUE must fit in 8 bits.

Effects: fail, write.

### `write16`

```gizlang
function write16(at: VirtualAddress<u16>, value: u64): void
```

Write VALUE as 16 bits at AT. VALUE must fit in 16 bits.

Effects: fail, write.

### `write32`

```gizlang
function write32(at: VirtualAddress<u32>, value: u64): void
```

Write VALUE as 32 bits at AT. VALUE must fit in 32 bits.

Effects: fail, write.

### `write64`

```gizlang
function write64(at: VirtualAddress<u64>, value: u64): void
```

Write VALUE as 64 bits at AT.

Effects: fail, write.

### `readPhysical`

```gizlang
function readPhysical(at: VirtualAddress<PhysicalAddress>): PhysicalAddress
```

Read the physical address stored at AT.

Effects: fail, read.

### `writePhysical`

```gizlang
function writePhysical(at: VirtualAddress<PhysicalAddress>, value: PhysicalAddress): void
```

Store the physical address VALUE at AT.

Effects: fail, write.

### `acquire`

```gizlang
function acquire(at: VirtualAddress<u64>): u64
```

Read the 64 bits at AT with acquire order.

Effects: read.

### `release`

```gizlang
function release(at: VirtualAddress<u64>, value: u64): void
```

Write VALUE at AT with release order.

Effects: write.

### `compareExchange`

```gizlang
function compareExchange(at: VirtualAddress<u64>, expected: u64, desired: u64): u64
```

Replace the 64 bits at AT with DESIRED if they are EXPECTED; the result is the old value.

Effects: fail, read, write.

### `compareExchange32`

```gizlang
function compareExchange32(at: VirtualAddress<u32>, expected: u64, desired: u64): u64
```

Replace the 32 bits at AT with DESIRED if they are EXPECTED; the result is the old value.

Effects: fail, read, write.

### `unsafeMmio`

```gizlang
function unsafeMmio<Device>(base: i64, bytes: i64): MmioRegion<Device>
```

The caller establishes device mapping, cache attributes, register permissions and lifetime.

### `mmioRead8`

```gizlang
function mmioRead8<Device>(region: MmioRegion<Device>, offset: i64): u64
```

Volatile register access through the compiler's target primitive. No implicit read-modify-write or atomic access.

### `mmioRead16`

```gizlang
function mmioRead16<Device>(region: MmioRegion<Device>, offset: i64): u64
```

Read the 16-bit register at OFFSET of REGION.

### `mmioRead32`

```gizlang
function mmioRead32<Device>(region: MmioRegion<Device>, offset: i64): u64
```

Read the 32-bit register at OFFSET of REGION.

### `mmioRead64`

```gizlang
function mmioRead64<Device>(region: MmioRegion<Device>, offset: i64): u64
```

Read the 64-bit register at OFFSET of REGION.

### `mmioWrite8`

```gizlang
function mmioWrite8<Device>(region: MmioRegion<Device>, offset: i64, value: u64): void
```

Write VALUE to the 8-bit register at OFFSET of REGION.

### `mmioWrite16`

```gizlang
function mmioWrite16<Device>(region: MmioRegion<Device>, offset: i64, value: u64): void
```

Write VALUE to the 16-bit register at OFFSET of REGION.

### `mmioWrite32`

```gizlang
function mmioWrite32<Device>(region: MmioRegion<Device>, offset: i64, value: u64): void
```

Write VALUE to the 32-bit register at OFFSET of REGION.

### `mmioWrite64`

```gizlang
function mmioWrite64<Device>(region: MmioRegion<Device>, offset: i64, value: u64): void
```

Write VALUE to the 64-bit register at OFFSET of REGION.

### `machine_load8`

```gizlang
function machine_load8(address: i64): u64 effects {read}
```

Read one byte at a physical or mapped address, zero-extended.

Effects: read.

### `machine_load16`

```gizlang
function machine_load16(address: i64): u64 effects {read}
```

Read 16 bits at an address, zero-extended.

Effects: read.

### `machine_load32`

```gizlang
function machine_load32(address: i64): u64 effects {read}
```

Read 32 bits at an address, zero-extended.

Effects: read.

### `machine_load64`

```gizlang
function machine_load64(address: i64): u64 effects {read}
```

Read 64 bits at an address.

Effects: read.

### `machine_store8`

```gizlang
function machine_store8(address: i64, value: u64): void effects {write}
```

Write the low byte of value at an address.

Effects: write.

### `machine_store16`

```gizlang
function machine_store16(address: i64, value: u64): void effects {write}
```

Write the low 16 bits of value at an address.

Effects: write.

### `machine_store32`

```gizlang
function machine_store32(address: i64, value: u64): void effects {write}
```

Write the low 32 bits of value at an address.

Effects: write.

### `machine_store64`

```gizlang
function machine_store64(address: i64, value: u64): void effects {write}
```

Write 64 bits at an address.

Effects: write.

### `machine_copy`

```gizlang
function machine_copy(to: i64, from: i64, count: i64): void effects {read, write}
```

Copy COUNT bytes from FROM to TO; the ranges may overlap (memmove).

Effects: read, write.

### `machine_fill`

```gizlang
function machine_fill(to: i64, value: u64, count: i64): void effects {write}
```

Fill COUNT bytes at TO with the low byte of VALUE (rep stosb).

Effects: write.

### `machine_cacheFlush`

```gizlang
function machine_cacheFlush(address: u64): void effects {read, write}
```

Clean and invalidate the cache line at ADDRESS. The caller checks its address and completes with machine_cacheSync.

Effects: read, write.

### `machine_cacheSync`

```gizlang
function machine_cacheSync(): void effects {read, write}
```

Complete preceding cache maintenance. This is separate from atomic memory ordering.

Effects: read, write.

### `machine_cacheType`

```gizlang
function machine_cacheType(): u64 effects {read}
```

AArch64 CTR_EL0: DminLine in bits 19:16 is the log2 of the data-cache line size in words.

Effects: read.

### `machine_atomicLoad`

```gizlang
function machine_atomicLoad(address: i64, order: i64 = 2): u64 effects {read}
```

Read an aligned 64-bit word. ORDER is C11's 0 relaxed, 2 acquire (default) or 5 sequentially consistent.

Effects: read.

### `machine_atomicStore`

```gizlang
function machine_atomicStore(address: i64, value: u64, order: i64 = 3): void effects {write}
```

Write an aligned 64-bit word. ORDER is C11's 0 relaxed, 3 release (default) or 5 sequentially consistent.

Effects: write.

### `machine_atomicLoad8`

```gizlang
function machine_atomicLoad8(address: i64, order: i64 = 2): u64 effects {read}
```

Read one byte atomically, zero-extended, with the same orders as machine_atomicLoad.

Effects: read.

### `machine_atomicStore8`

```gizlang
function machine_atomicStore8(address: i64, value: u64, order: i64 = 3): void effects {write}
```

Write the low byte atomically, with the same orders as machine_atomicStore.

Effects: write.

### `machine_atomicLoad16`

```gizlang
function machine_atomicLoad16(address: i64, order: i64 = 2): u64 effects {read}
```

Read an aligned 16-bit word atomically, zero-extended.

Effects: read.

### `machine_atomicStore16`

```gizlang
function machine_atomicStore16(address: i64, value: u64, order: i64 = 3): void effects {write}
```

Write the low 16 bits atomically to an aligned word.

Effects: write.

### `machine_atomicLoad32`

```gizlang
function machine_atomicLoad32(address: i64, order: i64 = 2): u64 effects {read}
```

Read an aligned 32-bit word atomically, zero-extended.

Effects: read.

### `machine_atomicStore32`

```gizlang
function machine_atomicStore32(address: i64, value: u64, order: i64 = 3): void effects {write}
```

Write the low 32 bits atomically to an aligned word.

Effects: write.

### `machine_compareExchange`

```gizlang
function machine_compareExchange(address: i64, expected: u64, desired: u64, order: i64 = 5, failure: i64 = -1): u64 effects {read, write}
```

Store DESIRED if the aligned word holds EXPECTED; return the old value. ORDER is C11's 0 relaxed, 2 acquire,
3 release, 4 acquire-release or 5 sequentially consistent (default). FAILURE is 0, 2 or 5, no stronger than ORDER;
-1 (default) takes ORDER's load part. Invalid orders trap before accessing memory.

Effects: read, write.

### `machine_compareExchange8`

```gizlang
function machine_compareExchange8(address: i64, expected: u64, desired: u64, order: i64 = 5, failure: i64 = -1): u64 effects {read, write}
```

The byte form of machine_compareExchange: low 8 bits participate and the old value is zero-extended.

Effects: read, write.

### `machine_compareExchange16`

```gizlang
function machine_compareExchange16(address: i64, expected: u64, desired: u64, order: i64 = 5, failure: i64 = -1): u64 effects {read, write}
```

The aligned 16-bit form of machine_compareExchange, with a zero-extended old value.

Effects: read, write.

### `machine_compareExchange32`

```gizlang
function machine_compareExchange32(address: i64, expected: u64, desired: u64, order: i64 = 5, failure: i64 = -1): u64 effects {read, write}
```

The aligned 32-bit form of machine_compareExchange, with a zero-extended old value. Adjacent bytes are untouched.

Effects: read, write.

### `machine_fetchAdd`

```gizlang
function machine_fetchAdd(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Add VALUE to an aligned word, wrapping at its width; return the old value. The orders are machine_compareExchange's.

Effects: read, write.

### `machine_fetchAdd8`

```gizlang
function machine_fetchAdd8(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Add at byte width, returning the old value zero-extended.

Effects: read, write.

### `machine_fetchAdd16`

```gizlang
function machine_fetchAdd16(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Add at aligned 16-bit width, returning the old value zero-extended.

Effects: read, write.

### `machine_fetchAdd32`

```gizlang
function machine_fetchAdd32(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Add at aligned 32-bit width, returning the old value zero-extended.

Effects: read, write.

### `machine_swap`

```gizlang
function machine_swap(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Replace an aligned word with VALUE; return the old value. The orders are machine_compareExchange's.

Effects: read, write.

### `machine_swap8`

```gizlang
function machine_swap8(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Swap a byte, returning the old value zero-extended.

Effects: read, write.

### `machine_swap16`

```gizlang
function machine_swap16(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Swap an aligned 16-bit word, returning the old value zero-extended.

Effects: read, write.

### `machine_swap32`

```gizlang
function machine_swap32(address: i64, value: u64, order: i64 = 5): u64 effects {read, write}
```

Swap an aligned 32-bit word, returning the old value zero-extended.

Effects: read, write.

### `machine_fence`

```gizlang
function machine_fence(order: i64 = 5): void effects {read, write}
```

A fence with machine_compareExchange's orders: relaxed does nothing, and the default orders all seqCst accesses.

Effects: read, write.

### `machine_in8`

```gizlang
function machine_in8(port: i64): u64 effects {read}
```

Read one byte from an x86 I/O port.

Effects: read.

### `machine_in16`

```gizlang
function machine_in16(port: i64): u64 effects {read}
```

Read 16 bits from an x86 I/O port.

Effects: read.

### `machine_in32`

```gizlang
function machine_in32(port: i64): u64 effects {read}
```

Read 32 bits from an x86 I/O port.

Effects: read.

### `machine_out8`

```gizlang
function machine_out8(port: i64, value: u64): void effects {write}
```

Write the low byte of value to an x86 I/O port.

Effects: write.

### `machine_out16`

```gizlang
function machine_out16(port: i64, value: u64): void effects {write}
```

Write the low 16 bits of value to an x86 I/O port.

Effects: write.

### `machine_out32`

```gizlang
function machine_out32(port: i64, value: u64): void effects {write}
```

Write the low 32 bits of value to an x86 I/O port.

Effects: write.

### `machine_halt`

```gizlang
function machine_halt(): void effects {write}
```

Stop the CPU until the next interrupt.

Effects: write.

### `machine_waitForInterrupt`

```gizlang
function machine_waitForInterrupt(): void effects {write}
```

With interrupts disabled, atomically enable them and halt, then return with interrupts disabled.
The x86 interrupt shadow closes the completion-before-halt race. Kernel mode only.

Effects: write.

### `machine_enable`

```gizlang
function machine_enable(): void effects {write}
```

Enable maskable interrupts.

Effects: write.

### `machine_disable`

```gizlang
function machine_disable(): void effects {write}
```

Disable maskable interrupts.

Effects: write.

### `machine_pause`

```gizlang
function machine_pause(): void effects {write}
```

Hint to the CPU that this is a spin-wait loop.

Effects: write.

### `machine_vector`

```gizlang
function machine_vector(vector: i64): i64 effects {fail}
```

The trap entry of vector 0..255. Other vectors fail. Every entry calls the kernel's `trap(frame): i64`.

Effects: fail.

### `machine_syscallEntry`

```gizlang
function machine_syscallEntry(): i64 effects {}
```

The trap entry for the syscall instruction (the LSTAR value); its frame has vector 256.

### `machine_invalidInstruction`

```gizlang
function machine_invalidInstruction(): void effects {write}
```

Deliberately raise the CPU's invalid-opcode exception, for fault-path validation.

Effects: write.

### `machine_lidt`

```gizlang
function machine_lidt(address: i64): void effects {write}
```

Load the interrupt descriptor table register from the descriptor at an address.

Effects: write.

### `machine_lgdt`

```gizlang
function machine_lgdt(address: i64): void effects {write}
```

Load the global descriptor table register from the descriptor at an address.

Effects: write.

### `machine_ltr`

```gizlang
function machine_ltr(selector: i64): void effects {write}
```

Load the task register with a TSS selector of the global descriptor table.

Effects: write.

### `machine_readControl`

```gizlang
function machine_readControl(register: i64): u64 effects {read, fail}
```

Read control register 0, 2, 3 or 4. Other registers fail.

Effects: fail, read.

### `machine_writeControl`

```gizlang
function machine_writeControl(register: i64, value: u64): void effects {write, fail}
```

Write control register 0, 2, 3 or 4. Writing 3 replaces the page-table root; kernel code must keep its mapping.

Effects: fail, write.

### `machine_readMsr`

```gizlang
function machine_readMsr(msr: i64): u64 effects {read}
```

Read a model-specific register.

Effects: read.

### `machine_writeMsr`

```gizlang
function machine_writeMsr(msr: i64, value: u64): void effects {write}
```

Write a model-specific register.

Effects: write.

### `machine_cpuid`

```gizlang
function machine_cpuid(leaf: i64, subleaf: i64, address: i64): void effects {write}
```

CPUID leaf and subleaf; eax, ebx, ecx and edx go to four u32 words at ADDRESS.

Effects: write.

### `machine_xgetbv`

```gizlang
function machine_xgetbv(number: i64): u64 effects {read}
```

XCR register NUMBER (XGETBV): XCR0 tells which register state the OS saves.

Effects: read.

### `machine_svmEnter`

```gizlang
function machine_svmEnter(registers: i64, guest: u64, host: u64): void effects {read, write}
```

Enter an AMD SVM guest and return at its next VM exit. Interrupts must be disabled and EFER.SVME enabled.
GUEST and HOST are physical VMCB addresses; VM_HSAVE_PA is set by the caller. REGISTERS holds 14 u64 words:
rbx, rcx, rdx, rsi, rdi, rbp, r8..r15. RAX, RSP and RIP are in the guest VMCB. The caller owns FPU state.

Effects: read, write.

### `machine_xsetbv`

```gizlang
function machine_xsetbv(index: i64, value: u64): void effects {write}
```

Write extended control register INDEX (XCR0 for 0): the state components that XSAVE manages.

Effects: write.

### `machine_xsave`

```gizlang
function machine_xsave(address: i64, mask: u64): void effects {write}
```

Save the extended state components in MASK to a 64-byte aligned ADDRESS.

Effects: write.

### `machine_xrstor`

```gizlang
function machine_xrstor(address: i64, mask: u64): void effects {write}
```

Restore the extended state components in MASK from a 64-byte aligned ADDRESS.

Effects: write.

### `machine_invalidatePage`

```gizlang
function machine_invalidatePage(address: i64): void effects {write}
```

Invalidate one virtual translation after a page-table update.

Effects: write.

### `machine_entry`

```gizlang
function machine_entry(callback: () => void): u64 effects {}
```

The address of a callback's C entry, for a vector table or a new stack.

### `machine_handler`

```gizlang
function machine_handler(callback: (a: i64, b: i64, c: i64) => void): u64 effects {}
```

The address of a callback's C entry that takes three integer or pointer arguments: a signal handler with SA_SIGINFO
(the signal, its siginfo, the interrupted context), or a C library hook.

### `machine_startSecondaryAarch64`

```gizlang
function machine_startSecondaryAarch64(cpu: u64): i64 effects {write}
```

PSCI HVC CPU_ON. The image supplies __secondary_stack_top and secondary(): void.
Returns the signed PSCI status; this does not grant SMP to a board without PSCI.

Effects: write.

### `machine_loadGs64`

```gizlang
function machine_loadGs64(offset: i64): u64 effects {read}
```

Read 64 bits at OFFSET from the GS base: in a kernel, the running CPU's own record.

Effects: read.

### `machine_storeGs64`

```gizlang
function machine_storeGs64(offset: i64, value: u64): void effects {write}
```

Write 64 bits at OFFSET from the GS base.

Effects: write.

### `machine_secondary`

```gizlang
function machine_secondary(): i64 effects {}
```

The secondary-CPU entry: 16-bit code a kernel copies to a page below 1 MiB, where INIT and SIPI start the other
CPUs. Its words: 8 its length in bytes (u32), 12 the page-table root (u32, below 4 GiB), 16 the base of the CPU
blocks, 24 their stride, 32 the ticket count (u32), 36 the last ticket that may enter (u32). Each CPU takes the
next ticket N, enters long mode on that root, sets its stack to the top of block N and calls the kernel's
`secondary(n: i64): void`; a CPU with a later ticket halts.

### `machine_cycles`

```gizlang
function machine_cycles(): u64 effects {read}
```

x86 TSC ticks, read once every earlier instruction has completed (lfence; rdtsc, as Linux reads the clock). Under
emulation these are virtual ticks, not CPU cycles.

Effects: read.

### `machine_floatStatus`

```gizlang
function machine_floatStatus(): u64 effects {read}
```

The floating-point status and control word: x86-64 MXCSR; AArch64 FPCR << 32 | FPSR; 0 on another CPU.

Effects: read.

### `machine_setFloatStatus`

```gizlang
function machine_setFloatStatus(value: u64): void effects {write}
```

Sets the word machine_floatStatus reads (nothing on another CPU).

Effects: write.

### `machine_rdrand`

```gizlang
function machine_rdrand(): u64 effects {read, fail}
```

Read a hardware random 64-bit value. The target retries until the CPU reports valid entropy.

Effects: fail, read.

### `machine_crc32c`

```gizlang
function machine_crc32c(state: u64, value: u64): u64 effects {}
```

CRC32C (Castagnoli) of STATE (its low 32 bits) updated with the eight little-endian bytes of VALUE, with no
inversion: one step of x86-64's crc32q (SSE4.2) or AArch64's crc32cx (which the caller checks the CPU has), and the
same value by a loop on another CPU.

### `machine_crc32`

```gizlang
function machine_crc32(state: u64, value: u64): u64 effects {}
```

CRC-32 (IEEE) of STATE as machine_crc32c: one step of AArch64's crc32x, and a loop on another CPU.

### `machine_crc32Fold`

```gizlang
function machine_crc32Fold(state: u64, data: i64, count: i64): u64 effects {read}
```

CRC-32 (IEEE) of STATE (its low 32 bits, not inverted) updated with the COUNT bytes at DATA, a multiple of 16 and at
least 64: four 128-bit lanes folded by carry-less multiplication, then a Barrett reduction (V. Gopal et al., "Fast
CRC Computation for Generic Polynomials Using PCLMULQDQ", Intel 2009; the constants of zlib's crc32_simd). x86-64
with PCLMULQDQ and SSE4.1, which the caller checks by CPUID.

Effects: read.

### `machine_sha256`

```gizlang
function machine_sha256(state: i64, data: i64, blocks: i64, constants: i64): u64 effects {read, write}
```

SHA-256 of the BLOCKS 64-byte blocks at DATA into STATE (8 32-bit words a to h), with CONSTANTS: the 64 round words
and then the 16 bytes 3, 2, 1, 0, 7, 6, 5, 4, 11, 10, 9, 8, 15, 14, 13, 12. BLOCKS is at least 1. 1 when it hashed
(x86-64 with the SHA extensions, which the caller checks by CPUID); 0 on another CPU, whose caller hashes in software.
It uses the vector registers: a kernel saves the state its thread holds there first.

Effects: read, write.

### `machine_process`

```gizlang
function machine_process(): i64 effects {read}
```

The process words of a freestanding Linux process (--emit-freestanding-linux): word 0 holds the stack the kernel
started the process on (argc, the arguments, the environment, the auxiliary vector); words 1-15 start at 0 and are
the process's own; words 16-21 are the bounds of the preinit, init and fini arrays (0 when the link has none).

Effects: read.

### `machine_linuxAbi`

```gizlang
function machine_linuxAbi(): i64 effects {}
```

The gizlang/linux ABI (X86_64, AARCH64, RISCV64, RISCV32 or XTENSA) of the CPU the code is built for: the CPU of a
freestanding Linux process (--emit-freestanding-linux CPU), else X86_64.

### `machine_os`

```gizlang
function machine_os(): i64 effects {}
```

The operating system of a runtime package (--emit-runtime-package CPU-OS): 1 Linux, 2 macOS, 3 Windows; 0 when the
build names none. A constant, so a branch for another system is folded away with its machine operations.

### `machine_setThreadPointer`

```gizlang
function machine_setThreadPointer(value: i64): void effects {write}
```

Sets the thread pointer that thread-local storage is reached from: FS on x86-64 (by arch_prctl), TPIDR_EL0 on
AArch64, tp on RISC-V, THREADPTR on Xtensa.

Effects: write.

### `machine_syscall`

```gizlang
function machine_syscall(nr: i64, a: i64, b: i64, c: i64, d: i64, e: i64, f: i64): i64 effects {read, write}
```

A Linux system call, without libc, in the register convention of machine_linuxAbi(). Only use it in a Linux
process.

Effects: read, write.

### `machine_syscallRiscv32`

```gizlang
function machine_syscallRiscv32(nr: i64, a: i64, b: i64, c: i64, d: i64, e: i64, f: i64): i64 effects {read, write}
```

RV32 Linux register convention (a7, a0..a5), returning a signed 32-bit result.

Effects: read, write.

### `machine_runRiscv32`

```gizlang
function machine_runRiscv32(entry: i64, stack: i64): i64 effects {read, write}
```

Run an RV32 machine-mode process until trap(frame) returns zero; return its a0 status.
The riscv32-process firmware entry supplies the register save/restore code. This grants no isolation.

Effects: read, write.

### `machine_syscallXtensa`

```gizlang
function machine_syscallXtensa(number: i64, a: i64, b: i64, c: i64, d: i64, e: i64, f: i64): i64 effects {read, write}
```

Xtensa Linux syscall register convention, with a signed 32-bit result.

Effects: read, write.

### `machine_runXtensa`

```gizlang
function machine_runXtensa(entry: i64, stack: i64, frame: i64): i64 effects {read, write}
```

Run native Xtensa code; frame is a caller-owned, aligned 112-byte context.
Initialize a4/a5/a6 at offsets 16/20/24 and PS at offset 76 before entry.

Effects: read, write.

### `machine_argument`

```gizlang
function machine_argument(list: i64): u64 effects {read, write}
```

The next integer or pointer argument of a C variadic call from the va_list at LIST: the value of a freestanding
export's last parameter `...arguments: i64` (64-bit CPUs).

Effects: read, write.

### `machine_argumentFloat`

```gizlang
function machine_argumentFloat(list: i64): f64 effects {read, write}
```

The next double argument of a C variadic call from the va_list at LIST, as machine_argument.

Effects: read, write.

### `machine_clone`

```gizlang
function machine_clone(flags: u64, stack: i64, parent: i64, tls: i64, child: i64, entry: (argument: i64) => void, argument: i64): i64 effects {read, write}
```

Linux clone(FLAGS) of a thread that starts on STACK and runs entry(ARGUMENT), then exits; PARENT, TLS and CHILD
are the kernel's parent TID address, thread pointer and child TID address. The new thread's ID or -errno.

Effects: read, write.

### `machine_signalReturn`

```gizlang
function machine_signalReturn(): u64 effects {}
```

The address of code that returns from a Linux signal handler (rt_sigreturn) on x86-64, the sa_restorer that
SA_RESTORER names; 0 on another CPU, whose kernel supplies one.

### `machine_longjmp`

```gizlang
function machine_longjmp(buffer: i64, value: i64): void effects {read, write}
```

Returns VALUE from the C setjmp that filled the buffer at BUFFER, on 64-bit Linux CPUs. Using it also defines the
C library's setjmp and _setjmp, which save the registers a call keeps, the stack pointer and the return address.

Effects: read, write.

### `machine_threadPointer`

```gizlang
function machine_threadPointer(): i64 effects {read}
```

The thread pointer machine_setThreadPointer set.

Effects: read.

### `machine_stackAddress`

```gizlang
function machine_stackAddress(): i64 effects {read}
```

An address in the calling frame: where its stack is now (a thread finds its stack bounds from it).

Effects: read.

