[SnowCheetos]

What this changes

kore.h could only be used from inside a Rust program: kore-ffi's
callbacks run in a Rust-founded host, and no crate built a shared object. A
C program a compiler writes on Kore had no runtime to call into. This adds
one, so the C surface works in an independent C program:

• kore-c, the runtime of libkore.so. A distribution builds the image
  from a one-line cdylib named kore (Kore's user/runtime/libkore),
  linked with --soname=libkore.so --no-undefined. It exports every
  kore.h function and the c-stdlib C names (malloc, pthread_create,
  ...), and installs the process heap.

• The program host. main runs on a main thread (a DoorbellWorker
  with a 1 MiB guarded stack), and thread 0 keeps the executor and the
  launch's faces. They share one request cell and one word, the shape
  kore-lua's VM bridge has, and every park is a doorbell park.

  • kore_fs_run(step, user, &error) (new kore/program.h) runs a
    KoreFsStep program as the program's filesystem session, through
    kore-ffi's Session over the launch's own face.
  • Any thread's exit ends the program. The host stops every other thread,
    runs the finalizers after a clean stop, and commits the C status through
    the C library's exit.

• Its headers ship with the image. kore-c declares links = "kore"
  and publishes the generated include directory as DEP_KORE_INCLUDE, so a
  distribution ships headers from the revision it built.

• A C program's threads park, never poll. pthreads run on kore-rt's
  thread controller. Its creators, its joiners and the controller itself
  each used to cede a millisecond at a time, and the controller probed
  every child for its exit on each pass. Now every wait is a futex park
  and every transition a futex wake.

  • The controller is the wake hub of the threads it founds. It mints each
    a doorbell and relays the wakes they cannot deliver to each other.
  • A thread's end reaches it through the exit hook thread::exit runs.
    Its reap parks on a join arm beside its word.
  • kore_thread_join parks on its target's retirement word, which the
    controller wakes.
  • kore-c founds main holding a channel-space grant to mint the
    doorbells from. Without one the controller still runs, on the deadline
    park.

• A native re-export at Kore 0018956a (MicroPerceptron/kore#1494's
  branch). kore-rt gains the pieces the host needs:

  • startup::barrier: the process barrier without the exit;
  • managed threads that inherit their founder's wake send;
  • crash::report: a panic's report without the thread's end;
  • the parking thread controller, with the futex pieces under it: adopted
    peer sends, a relay Hub, and wait_or_end.

• Threads that found take a founder's arena (c476f32 re-exports Kore at 2a0730dd, 5be44eb at 6c57f344). C main is a doorbell worker, so it founds with the 256-slot founding granule, and a committed founding returns the names nothing binds any more. Before this, kore_spmd_dispatch refused from main (status 7) and a C program kept at most two pthreads alive. The founder's record of a founding's staged space keeps binding until the reap, so that one name waits for the join (MicroPerceptron/kore#1537).

• stdio for C programs (13b0a91, 0460f5c). The re-export at Kore 2d4998ba carries Kore's C library, kore-c-shim. It provides:

  • the printf family over every C17 conversion, floats exact, long double in x87's and binary128's formats;
  • the standard streams, behind an installable sink whose lock one C call holds across its writes;
  • <string.h>, <stdlib.h>'s parsers, qsort and errno.

  libkore.so links it without its allocator and abort, which libkore exports itself, and writes stdout and stderr for every thread:

  • A writer holds the streams' lock for its whole C call, as flockfile does, so one call's output is never split by another thread's. It copies into a 16 KiB in-process ring and kicks the host only if the host armed itself before parking, so a loop of printf costs no trap per call. The host can kick main but holds no send into a pthread's doorbell, so every wait for room is bounded by the runtime's slice.
  • The host, thread 0, which the launcher's stream is bound to, drains a pass at a time: what was queued when the pass began. It waits for the launcher's capacity rather than dropping output, and between passes it serves the program's end and its filesystem sessions.
  • The host's own writes (a filesystem step's callbacks run on it) cannot wait for the host. They are kept in order beside the ring, each stamped with the ring position it follows.
  • The end drains what was queued and closes the stream before the process ends, so the launcher shows the output before the status. An end committed on the host itself relays at once what the launcher has room for, and a write after the end reports EOF.
  • abort ends the program with the aborted status (134 at the shell) from any thread, running no atexit handler. cbindgen leaves it out of kore/program.h, since C declares it in <stdlib.h>.

• Descriptors over the capabilities a C program holds, and mmap (23a0ca0, c876e43). open, close, mmap and munmap are C's spelling for using a capability the program was founded holding, and add no authority:

  int fd = open("/kore/memory", O_RDWR);
  char *region = mmap(NULL, 1 << 20, PROT_READ | PROT_WRITE, MAP_PRIVATE, fd, 0);

  • A path names no file. open looks it up in one static table (crates/c/src/fd.rs) whose rows are a name and the bootstrap coordinate (role, index) it stands for. It answers a descriptor only for a capability the calling thread holds, with access its rights cover. The first name is /kore/memory, role::HEAP@0, the supply the allocator grows on.
  • A descriptor stores the coordinate, never the capability. Capabilities are per thread on Kore, so each use resolves the coordinate in the calling thread's boot block. Numbers are the process's, from 3, and no authority crosses a thread through one. close forgets the number.
  • mmap on the supply answers fresh, zeroed memory, by the sequence a Wasmtime engine's guest memory takes: a lease from the supply's top (heap::reserve_from_top, clear of the allocator), an address from the free part of the link window (Rt::link_free_span, new in the re-export at Kore 10c7b400), the whole lease mapped there. The caller never picks the address, and nothing a program wrote is executable.
  • Thread 0 maps, for whichever thread asked, over one request cell, as it serves a filesystem session. The share of the supply a thread is founded with carries no REVOKE, and a region that can be unmapped again is a carve its holder may revoke; the supply's root is thread 0's. A mapping is the process's, and any thread may munmap it.
  • munmap parks the region. The supply's and the window's cursors only advance, so the program keeps the lease and its address, and the next mmap of that length takes it again, zeroed. Lengths that never repeat each spend supply, and a program holds sixteen regions.
  • kore_fd_describe (kore/program.h) reads a descriptor's kind, what its capability's rights permit, and a supply's length.
  • The streams' futex lock moves to lock.rs, which the request cell's callers share. kore-ld joins the owner paths for its SharedPlacer.

• main receives its arguments (4289361 re-exports Kore at dfece644, 2ce41f1). Kore's process page now carries the name a launcher resolved a program by beside the tail of its command line. The host reads both once, on thread 0 before the main thread exists, and splits the tail as every Kore program that wants words does: a POSIX shell's quoting without expansion. The C library's start asks for the vector through a third lifecycle hook, __kore_program_arguments(&argv):

  • argv[0] is the name, or the empty string when the launcher gave none; argv[argc] is null; the strings are the program's to change.
  • A line that does not split (an unclosed quote, a lone trailing backslash, a NUL inside a word) is not handed to main. The host says why on stderr and ends the program with status 5 before it runs.
  • A launch that carried no page, or no host, runs with argc zero. envp is empty.

Coverage and checks

• tools/check-program.py (make cross, and a CI step per ISA) links
  libkore.so as a distribution does and checks it:
  • a library with no entry point;
  • its soname, nothing needed or undefined;
  • static initial-exec TLS;
  • exactly the declared ABI and the C library's names exported (130 symbols on every ISA).
• kore/program.h is generated by cbindgen 0.29.4 like kore.h, includes
  it, and declares none of its types again. bindings-check compiles a C
  consumer of it for every ISA.
• Host tests cover the C entry's refusals and the exit word's encoding and
  first-request rule. kore-rt's own host suite (460 tests, run here through
  the native export) covers the controller's join handshake, the relay's
  order (counted before the hub's word moves), and the sweep's choice of
  threads.
• Host tests cover the relay's ring, which is the code the target runs: a
  write framed into records and read back in order, the wrap of its bytes
  and positions, room counted with headers, a stale read that never finds
  room that is not there, the discard, and the order of the host's held
  writes.
• Host tests cover the descriptor table and the mapping rules: a path is a
  row or nothing, only an access mode is a flag, access is held to the
  capability's rights, the lowest free number is handed out from 3, threads
  never share a descriptor, each mmap request with no meaning is refused
  by its errno, and an unmapped region serves the next request of its
  length.
• Host tests cover the argument vector: the command is the first word and
  the tail follows as a shell splits it, every word is its own terminated
  string, and a line that does not split, or holds a NUL, is no vector.
• Run here on 2ce41f1: make fmt test check docs owners bindings-check miri, the native type composition, and for each ISA the target check,
  check-entry, check-alloc-symbols and check-program, all green.

Evidence

• Kore's make keytest-tcc-x86 compiles a C program at Kore's shell
  against these headers, links libkore.so and runs it to exit 42. The
  program uses the heap, the clock, random, a hash table and a
  kore_fs_run session. The shell reads back the file the session wrote and
  the one the atexit handler wrote as the program ended. Its threads:

  • one that fills a buffer;
  • one that ends through pthread_exit;
  • one that creates and joins its own;
  • a detached one;
  • one parked on a futex word that only main wakes. main holds no send
    into that thread, and with cancellation disabled the wait has no slice
    to fall back on, so only the controller's relay can end it.

  On MicroPerceptron/kore#1494's branch (source 4633d3cc, sealed in
  76fddb9f, pinning this branch's b9eb3c2), the keytest passes on the
  production image:
  libkore-tour: linked 3 segments; exit 42. The shell then reads back
  written and read back through kore_fs_run and the atexit handler ran.

• stdio, on the same branch (source 1db2c9da, sealed in 0de59be2,
  pinning this branch's 0460f5c): the keytest compiles the shipped
  hello.c with no flag, installs it and runs it. Every line reaches the
  terminal: integers, strings, floats in each style, an snprintf into its
  own buffer and a line on stderr. Its zero status prints nothing. A
  one-line program then prints a long double with x87's digits
  (0.1000000000000000000013553) and aborts, which ends it with
  exit 134 after what it wrote. The tour above now also keeps two dozen
  threads alive at once and dispatches an SPMD gang from main.

• Descriptors and mmap, on the same branch (source 7068bea1, sealed in
  f2644e5b, pinning this branch's c876e43): the keytest compiles the
  shipped memory.c with no flag, installs it and runs it to status 0. It
  prints descriptor 3 is memory: readable, writable, a 16 MiB supply,
  maps a megabyte (zeroed), writes and reads it back, maps a second
  elsewhere, takes a region it had again after munmap, and is refused an
  unknown name, a file flag, an offset, part of a mapping and a closed
  descriptor.

• Arguments, on the same branch (source 1510049d, sealed in fd5919ac,
  pinning this branch's 2ce41f1): the keytest types a program that prints
  its argv. Run as args one 'two words' "" four it prints its name and
  four words, the quoted one whole and the empty one kept, and returns 45;
  run alone it prints its name; and args 'open never reaches main:
  kore: the ' opened at byte 0 is never closed, exit 5.

• stdio, mmap and arguments have run on x86_64 only: in QEMU, and stdio
  and mmap (from threads other than main too) on an x86 laptop. No
  aarch64 or riscv64 boot has run a C program that prints, maps or takes
  arguments, and arguments have not run on hardware.

• This repository's checks are compiler and link evidence, not boot or
  hardware evidence.

Not in this change

• stdin, FILE streams over files (fopen), and an environment: envp
  is the empty vector.
• Names for anything but the program's memory supply: device memory,
  interrupts and DMA, and sending a region to another task.
• Task preparation (kore_task_*) still needs a Rust host to admit its
  batch.
• Zig programs are not hosted: the Zig module still targets the Rust-hosted
  adapter.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ACHC7gwT8vVUKqPGAjXfMM

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[SnowCheetos]

The red copilot-pull-request-reviewer check on 2ce41f1 is not a result about this branch. The reviewer agent never started its review: its job log ends with SessionModelError: You have exceeded your monthly quota. The seven CI checks that build and test the branch (host, miri, the three target checks, lockfile currency and advisories) all pass on the same commit.

Nothing in the diff can change it; it clears when the Copilot quota resets or the review is re-requested.

---

Generated by Claude Code