coro: add the stackless preemptive runtime core

.github/workflows/coroutine.yml

@@ -0,0 +1,255 @@
+name: Coroutine
+
+on:
+  pull_request:
+    branches:
+      - main
+      - llvm-coro
+      - "coro/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.check }}
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { llvm: 19, go: "1.26.5", tags: "llvm19", lane: "compat", check: "test (19, 1.26.5, llvm19)" }
+          - { llvm: 20, go: "1.26.5", tags: "llvm20", lane: "compat", check: "test (20, 1.26.5, llvm20)" }
+          - { llvm: 21, go: "1.26.5", tags: "llvm21", lane: "compat", check: "test (21, 1.26.5, llvm21)" }
+          - { llvm: 22, go: "1.26.5", tags: "llvm22", lane: "compat", check: "test (22, 1.26.5, llvm22)" }
+          - { llvm: 19, go: "1.26.5", tags: "llvm19", lane: "integration", check: "test integration (19, 1.26.5, llvm19)" }
+          - { llvm: 19, go: "1.26.5", tags: "llvm19", lane: "targets", check: "test targets (19, 1.26.5, llvm19)" }
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install LLVM
+        run: |
+          echo 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-${{ matrix.llvm }} main' | sudo tee /etc/apt/sources.list.d/llvm.list
+          wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends llvm-${{ matrix.llvm }}-dev clang-${{ matrix.llvm }} lld-${{ matrix.llvm }} libgc-dev
+          echo '/usr/lib/llvm-${{ matrix.llvm }}/bin' >> "$GITHUB_PATH"
+
+      - name: Set up Go
+        uses: ./.github/actions/setup-go
+        with:
+          go-version: ${{ matrix.go }}
+
+      # This focused LLVM/runtime matrix complements the regular upstream Go,
+      # cache, LLGo and target workflows, including their macOS lanes.
+      - name: Test coroutine analysis
+        if: matrix.lane == 'integration'
+        run: go test -race -shuffle=on ./internal/coro
+
+      - name: Test target-neutral coroutine runtime core
+        if: matrix.lane == 'compat'
+        run: |
+          cd runtime
+          go test -race -shuffle=on ./internal/coroalloc -count=1
+          go test -race -shuffle=on ./internal/coro -count=1
+          go test -race -shuffle=on ./internal/corodoorbell -count=1
+          # The run-decision wrapper needs the production coro package but a
+          # test-local abort shim, so select its two sources instead of loading
+          # the complete LLGo runtime package into the host Go runtime.
+          go test -race -shuffle=on -tags=coro_run_decision_abi_test \
+            ./internal/runtime/coro_run_decision.go \
+            ./internal/runtime/coro_run_decision_test.go \
+            -run '^Test(CoroRunDecisionOutputModeV1|NormalCoroRunDecisionWordsV1|CoroRunDecisionWrapperRejectsMalformedNormalOnlyMode)$' -count=1
+          go test . -run '^(TestCoroNativeTargetBuildSelection|TestCoroTimerOwnerV2SourceABI|TestTimeSleep)' -count=1
+          # The complete LLGo runtime package intentionally owns symbols that
+          # collide with the host Go runtime. Use the real production adapter
+          # sources plus test-only definitions of the compiler-owned C wrappers
+          # to exercise begin/run/destroy without adding production callbacks.
+          # Compiler tests separately cover the LLVM/LLGo side; this is not a
+          # cross-language linked smoke test.
+          go test -race -shuffle=on -tags=coro_runtime_adapter_test \
+            ./internal/runtime/coro_run_slice.go \
+            ./internal/runtime/coro_program.go \
+            ./internal/runtime/coro_sched.go \
+            ./internal/runtime/coro_executor.go \
+            ./internal/runtime/coro_panic_payload.go \
+            ./internal/runtime/coro_executor_driver_legacy.go \
+            ./internal/runtime/coro_ready_distribution_default.go \
+            ./internal/runtime/coro_target_executor_retired_default.go \
+            ./internal/runtime/coro_target_test_adapter.go \
+            ./internal/runtime/coro_program_test.go \
+            -run '^TestCoroProgram' -count=1
+          # The native fleet is a deliberately isolated production adapter:
+          # select only its real source plus its host test so LLGo runtime
+          # symbols do not collide with the host Go runtime.
+          go test -race -shuffle=on -tags=coro_native_fleet_test \
+            ./internal/runtime/coro_run_slice.go \
+            ./internal/runtime/coro_ready_distribution_default.go \
+            ./internal/runtime/coro_native_fleet.go \
+            ./internal/runtime/coro_native_fleet_reactor.go \
+            ./internal/runtime/coro_native_fleet_test.go \
+            -run '^TestCoroNativeFleet' -count=1
+          GOOS=js GOARCH=wasm CGO_ENABLED=0 go test \
+            -tags=coro_runtime_adapter_test \
+            -exec="$(go env GOROOT)/lib/wasm/go_js_wasm_exec" \
+            ./internal/runtime/coro_run_slice.go \
+            ./internal/runtime/coro_program.go \
+            ./internal/runtime/coro_sched.go \
+            ./internal/runtime/coro_executor.go \
+            ./internal/runtime/coro_panic_payload.go \
+            ./internal/runtime/coro_executor_driver_legacy.go \
+            ./internal/runtime/coro_ready_distribution_default.go \
+            ./internal/runtime/coro_target_executor_retired_default.go \
+            ./internal/runtime/coro_target_test_adapter.go \
+            ./internal/runtime/coro_program_test.go \
+            -run '^TestCoroProgram' -count=1
+          # Exercise the production typed hchan queue and exact coroutine
+          # source transaction together. The host atomic shim exercises the
+          # portable no-suspend channel gate without an OS mutex dependency.
+          go test -race -shuffle=on -tags='coro_channel_adapter_test,coro_channel_owner_test' \
+            ./internal/runtime/z_chan.go \
+            ./internal/runtime/z_chan_coro.go \
+            ./internal/runtime/z_chan_lock_coro.go \
+            ./internal/runtime/z_chan_lock_coro_atomic_host.go \
+            ./internal/runtime/coro_channel_adapter_test.go \
+            ./internal/runtime/coro_channel_owner_lock_test.go \
+            -run '^TestCoroChannelAdapter' -count=1
+          GOOS=js GOARCH=wasm CGO_ENABLED=0 go test \
+            -tags='coro_channel_adapter_test,coro_channel_owner_test' \
+            -exec="$(go env GOROOT)/lib/wasm/go_js_wasm_exec" \
+            ./internal/runtime/z_chan.go \
+            ./internal/runtime/z_chan_coro.go \
+            ./internal/runtime/z_chan_lock_coro.go \
+            ./internal/runtime/z_chan_lock_coro_atomic_host.go \
+            ./internal/runtime/coro_channel_adapter_test.go \
+            ./internal/runtime/coro_channel_owner_lock_test.go \
+            -run '^TestCoroChannelAdapter' -count=1
+          # Semaphore and notify waits share one POD-only keyed registry. Race
+          # the exact production registry source to lock FIFO selection,
+          # generation reuse, cancellation, and single-owner posting.
+          go test -race -shuffle=on -tags=coro_sema_owner_test \
+            ./internal/runtime/z_chan_lock_coro.go \
+            ./internal/runtime/z_chan_lock_coro_atomic_host.go \
+            ./internal/runtime/coro_keyed_park.go \
+            ./internal/runtime/coro_keyed_post_test.go \
+            ./internal/runtime/coro_keyed_registry_test.go \
+            -run '^TestCoroKeyed' -count=1
+          go test ./internal/corotimer -run '^TestDeadlineAfter$' -count=1
+
+      - name: Link named freestanding WebAssembly targets
+        if: matrix.lane == 'targets'
+        env:
+          LLGO_WASM_TARGET_SMOKE: "1"
+        run: |
+          go test -v ./internal/crosscompile -run '^TestFreestandingWasmTargetToolchainSmoke$' -count=1
+          go build -o /tmp/llgo-wasm-target ./cmd/llgo
+          for target in wasip2 wasm-unknown; do
+            output="/tmp/llgo-${target}.wasm"
+            LLGO_BUILD_CACHE=off LDFLAGS='--export=main' \
+              /tmp/llgo-wasm-target build -target="$target" -o "$output" \
+              ./internal/crosscompile/testdata/wasm_allocator
+            test "$(od -An -t x1 -N4 "$output" | tr -d ' \n')" = '0061736d'
+            symbols="$(llvm-nm --defined-only --format=just-symbols "$output")"
+            for symbol in main malloc free sbrk abort; do
+              grep -Fx "$symbol" <<<"$symbols"
+            done
+            ! grep -E '^GC_' <<<"$symbols"
+            test -z "$(llvm-nm --undefined-only --format=just-symbols "$output")"
+            if command -v wasmtime >/dev/null; then
+              result="$(wasmtime run --invoke main "$output" 0 0)"
+              test "$result" = '0'
+            fi
+          done
+
+      - name: Compile coroutine runtime adapter across targets
+        if: matrix.lane == 'targets'
+        run: |
+          cd runtime
+          GOOS=js GOARCH=wasm CGO_ENABLED=0 go test -c -o /tmp/coro-js-wasm.test ./internal/runtime
+          GOOS=wasip1 GOARCH=wasm CGO_ENABLED=0 go test -c -o /tmp/coro-wasip1-wasm.test ./internal/runtime
+          GOOS=linux GOARCH=arm CGO_ENABLED=0 go test -c -o /tmp/coro-linux-arm.test ./internal/runtime
+          GOOS=linux GOARCH=riscv64 CGO_ENABLED=0 go test -c -o /tmp/coro-linux-riscv64.test ./internal/runtime
+          GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go test -c -o /tmp/coro-doorbell-linux-arm64.test ./internal/corodoorbell
+          GOOS=linux GOARCH=riscv64 CGO_ENABLED=0 go test -c -o /tmp/coro-doorbell-linux-riscv64.test ./internal/corodoorbell
+          GOOS=linux GOARCH=arm CGO_ENABLED=0 go test -c -tags='baremetal cortexm' -o /tmp/coro-cortexm-baremetal.test ./internal/runtime
+
+      - name: Test coroutine build integration
+        if: matrix.lane == 'integration'
+        # Keep the focused workflow exhaustive for the build-side coroutine
+        # contract. This includes park effect seeding, frozen foreign noblock
+        # certificates, IRQUnsafe handling, the explicit-status panic stop, and
+        # the native linked static-spawn scheduler-island execution smoke. The
+        # timer checks have their own LLVM 19-22 steps below, so do not run them
+        # twice in the LLVM 19 job.
+        run: go test ./internal/build -run 'Coro|Coroutine' -skip '^TestCoroNativeTimeSleepProductionPlanAndCodegen$' -timeout=10m -count=1
+
+      - name: Verify production time.Sleep coroutine plan
+        if: matrix.lane == 'compat'
+        run: go test -tags='${{ matrix.tags }}' -v ./internal/build -run '^TestCoroNativeTimeSleepProductionPlanAndCodegen$' -timeout=10m -count=1
+
+      - name: Test coroutine compiler integration
+        if: matrix.lane == 'integration'
+        run: |
+          go test -race ./cl/ssawrap -count=1
+          go test -race ./cl -run '^Test(CompilationCoroPlanObservationAndCacheRegistration|CoroEntryResolutionPlainPrimaryPreservesIR|ResolveFunctionSymbolUsesPrimaryAndExactPlan|CoroEntryRejectsUnsupportedBeforeCreatingSymbol|CoroEntryResolutionPreflightRejectsWholePlanBeforeCodegen|CoroEntryResolutionPreflightRejectsMissingPlanAndCache|Emission.*)$' -count=1
+          # Compile and execute one ordinary program through LLGo so the new
+          # runtime glue is checked by LLGo itself, not only by the host Go compiler.
+          go test ./cl -run '^TestRunAndTestFromTestgo/print$' -count=1
+
+      - name: Test structured LLVM coroutine builder
+        if: matrix.lane == 'compat'
+        run: go test -tags='${{ matrix.tags }}' -v ./ssa -run '^TestCoro' -count=1
+
+      - name: Test canonical coroutine plan digest and cache identity
+        if: matrix.lane == 'compat'
+        run: |
+          go test -tags='${{ matrix.tags }}' ./internal/coro -run '^TestCoroPlanDigest' -count=1
+          go test -tags='${{ matrix.tags }}' ./internal/build -run '^Test(BuildCoroPlanInstallsArchiveDigest|CoroutinePlanInputsAffectFingerprint|CoroEntryResolutionUsesPlanMatchedPackageCache|CoroPlanDigestMetadataUsesEffectiveLLVMTarget|CoroPhysicalABICacheRegistrationPreservesCollectedFuncInfo)$' -count=1
+          go test -tags='${{ matrix.tags }}' ./cl -run '^Test(CompilationCoroABIIdentityValidation|CoroEntryResolutionCacheRegistrationWithDigest|CoroPhysicalABICacheRegistrationPreservesPhysicalMetadata)$' -count=1
+
+      - name: Test coroutine physical ABI and function dispatch lowering
+        if: matrix.lane == 'compat'
+        # Run every compiler test whose name is part of the coroutine contract;
+        # in particular this covers pure SSA aggregates/PHI and caller-frame
+        # park lowering on native64 and wasm32 before and after CoroSplit.
+        run: go test -tags='${{ matrix.tags }}' -v ./cl -run '^Test(Coro|EmissionUniverse(ActiveABIMethodTablesUseFrozenWrapperSymbols|ABIMethodDemandReferencesAreExactRecursiveAndOwnerScoped))' -count=1
+
+      - name: Test coroutine TLS function dispatch proof
+        if: matrix.lane == 'compat'
+        run: go test -tags='${{ matrix.tags }}' -v ./internal/build -run '^TestCoroTLS' -count=1
+
+      - name: Test coroutine registry and control integration
+        if: matrix.lane == 'compat'
+        run: go test -tags='${{ matrix.tags }}' -v ./internal/build -run '^Test(CollectLinkedCoroRootAnchors|ActiveCoroABIVersions|BuildCoroPlanErrors|CoroProgramManifest.*|CoroProgramBootstrap.*|SelectCoroProgramBootstrap.*|GenMainModule.*Coro.*)$' -count=1
+
+      - name: Test LLVM 22 tool configuration
+        if: matrix.lane == 'compat' && matrix.llvm == 22
+        run: go test -tags=llvm22 ./xtool/env/llvm ./internal/xtool/llvm
+
+      - name: Test resolved LLVM target configuration
+        if: matrix.lane == 'targets'
+        run: |
+          go test ./internal/xtool/llvm -run '^TestGetTarget(Spec|Triple)$' -count=1
+          go test ./internal/crosscompile -run '^Test(UseTarget|UseExportsResolvedLLVMConfig|ResolvedLLVMTargetSpecWASIThreads)$' -count=1
+          go test ./internal/cabi -run '^TestDevLTOGlobalDCETargetArchAndNewTransformerArchSelection$' -count=1
+          go test -v ./ssa -run '^Test(ResolvedTargetConfig(|IsAuthoritativeAndFrozen)|TargetDataLegacyLayoutCompatibility|ResolvedPointerWidthMismatchFallsBack|NewProgramDefaultTargetCompatibility|ResolvedExternalBackendCompatibilityFallback|ResolvedTargetABINameControlsRISCVObject)$' -count=1
+          go test ./internal/build -run '^Test(NewLLSSATargetUsesResolvedLLVMConfig|LLVMCPUAndFeaturesAffectBuildFingerprint|DefaultTargetKeepsLegacyCacheIdentity|NonDefaultLLVMFeaturesEnterCacheIdentity|ResolvedTargetCompatibilityAudit)$' -count=1
+
+      - name: Check llgo-tag build
+        if: matrix.lane == 'integration'
+        run: go test -tags=llgo ./internal/coro
+
+      - name: Vet coroutine analysis
+        if: matrix.lane == 'integration'
+        run: |
+          go vet ./internal/coro ./internal/build ./cl/ssawrap ./internal/xtool/llvm ./internal/crosscompile ./internal/cabi
+          # The runtime package has pre-existing unsafe.Pointer findings.
+          (cd runtime && go vet ./internal/coro && go vet -unsafeptr=false ./internal/runtime)
+          # The compiler package has a pre-existing unsafe.Pointer finding.
+          # Disable only that analyzer and keep all other checks enabled.
+          go vet -unsafeptr=false ./cl
+          # The SSA package has pre-existing sync.Map copylocks findings. Keep
+          # every other analyzer active while coroutine slices are integrated.
+          go vet -copylocks=false ./ssa

.github/workflows/fmt.yml

@@ -32,8 +32,13 @@ jobs:
             pushd "$dir" >/dev/null
             # gofmt won't traverse directories that start with '_' or 'testdata',
             # so mirror dev/local_ci.sh and scan every Go file explicitly.
+            # pthread.go intentionally keeps c2go's spaced `// llgo:link`
+            # directive adjacent to `//llgo:coro`; gofmt splits that single
+            # FuncDecl doc group and changes the compiler-visible contract.
             fmt_output="$(
-              find . -name '*.go' -type f ! -name 'xgo_autogen.go' -print0 \
+              find . -name '*.go' -type f ! -name 'xgo_autogen.go' \
+                ! -path './runtime/internal/clite/pthread/pthread.go' \
+                ! -path './internal/clite/pthread/pthread.go' -print0 \
                 | xargs -0 gofmt -l \
                 | sed 's|^\\./||' \
                 || true

.github/workflows/targets.yml

@@ -15,7 +15,10 @@ concurrency:
 
 jobs:
   llgo:
-    timeout-minutes: 30
+    # The empty and defer probes compile the complete embedded target catalog
+    # sequentially. Coroutine planning makes the combined lane exceed the old
+    # 30-minute budget on hosted runners even while targets keep succeeding.
+    timeout-minutes: 45
     strategy:
       matrix:
         os:

_demo/embed/targetsbuild/build.sh

@@ -215,9 +215,27 @@ for target in "${targets_to_build[@]}"; do
 		continue
 	fi
 
-	output=$(../../../dev/llgo.sh build -target $target -o hello.elf "./$test_dir" 2>&1)
-	if [ $? -eq 0 ]; then
-		echo ✅ $target `file hello.elf`
+	# The named wasm target is the Emscripten environment, not the freestanding
+	# wasm-unknown or WASI target. Keep target resolution honest and report a
+	# missing optional SDK as a capability warning; dedicated WebAssembly jobs
+	# exercise the toolchain-independent wasm targets.
+	if [[ "$target" == "wasm" ]] && ! command -v emcc >/dev/null 2>&1; then
+		echo ⚠️ $target "(Emscripten SDK is not installed; wasm-unknown and WASI are tested separately)"
+		warned_targets+=("$target")
+		continue
+	fi
+
+	if output=$(../../../dev/llgo.sh build -target "$target" -o hello.elf "./$test_dir" 2>&1); then
+		artifact=hello.elf
+		if [[ "$target" == "wasm" ]]; then
+			artifact=hello.elf.wasm
+		fi
+		if [ ! -f "$artifact" ]; then
+			echo ❌ "$target (build succeeded without expected artifact $artifact)"
+			failed_targets+=("$target")
+			continue
+		fi
+		echo ✅ "$target $(file "$artifact")"
 		successful_targets+=("$target")
 	else
 		# Check if output contains warning messages

cl/_testdata/llgosyscall/in.go

@@ -12,10 +12,13 @@ func syscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 //go:linkname syscall6X llgo.syscall
 func syscall6X(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 
+//go:linkname syscall32 llgo.syscall32
+func syscall32(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr)
+
 //go:linkname syscall5f64 llgo.syscall
 func syscall5f64(fn, a1, a2, a3, a4, a5 uintptr, f1 float64) (r1, r2, err uintptr)
 
-//go:linkname syscallPtr llgo.syscall
+//go:linkname syscallPtr llgo.syscallPtr
 func syscallPtr(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr)
 
 //go:linkname rawSyscall llgo.syscall
@@ -36,6 +39,15 @@ func Use() uintptr {
 	return r1
 }
 
+// CHECK-LABEL: define i64 @"{{.*}}/llgosyscall.Use32"(){{.*}} {
+// CHECK:   %[[R:[0-9]+]] = call i64 null(i64 1, i64 2, i64 3)
+// CHECK:   %[[LOW:[0-9]+]] = trunc i64 %[[R]] to i32
+// CHECK:   %{{[0-9]+}} = icmp eq i32 %[[LOW]], -1
+func Use32() uintptr {
+	r1, _, _ := syscall32(0, 1, 2, 3)
+	return r1
+}
+
 // CHECK-LABEL: define i64 @"{{.*}}/llgosyscall.Use5F64"(i64 %0, double %1){{.*}} {
 // CHECK:   %{{[0-9]+}} = inttoptr i64 %0 to ptr
 // CHECK:   %{{[0-9]+}} = call i64 %{{[0-9]+}}(i64 1, i64 2, i64 3, i64 4, i64 5, double %1)
@@ -79,7 +91,7 @@ func Use6X() uintptr {
 // CHECK-LABEL: define i64 @"{{.*}}/llgosyscall.UsePtr"(){{.*}} {
 // CHECK-NEXT: _llgo_0:
 // CHECK-NEXT:   %0 = call i64 null(i64 1, i64 2, i64 3)
-// CHECK-NEXT:   %1 = icmp eq i64 %0, -1
+// CHECK-NEXT:   %1 = icmp eq i64 %0, 0
 // CHECK-NEXT:   %2 = call i32 @cliteErrno()
 // CHECK-NEXT:   %3 = sext i32 %2 to i64
 // CHECK-NEXT:   %4 = select i1 %1, i64 %3, i64 0