Add goroutine core affinity support for RP2040/RP2350 systems

src/examples/core-pinning/main.go

@@ -0,0 +1,111 @@
+// This example demonstrates goroutine core pinning on multi-core systems (RP2040/RP2350).
+// It shows how to pin goroutines to specific CPU cores and verify their execution.
+
+//go:build rp2040 || rp2350
+
+package main
+
+import (
+	"machine"
+	"runtime"
+	"time"
+)
+
+func main() {
+	time.Sleep(5 * time.Second)
+	println("=== Core Pinning Example ===")
+	println("Number of CPU cores:", runtime.NumCPU())
+	println("[main] Main starting on core:", machine.CurrentCore())
+	println()
+
+	// Example 1: Pin using standard Go API (LockOSThread)
+	// This pins to whichever core this goroutine is currently running on
+	runtime.LockOSThread()
+	println("[main] Pinned using runtime.LockOSThread()")
+	println("[main] Running on core:", machine.CurrentCore())
+	runtime.UnlockOSThread()
+	println("[main] Unpinned using runtime.UnlockOSThread()")
+	println()
+
+	// Example 2: Pin to a specific core using machine package
+	machine.LockCore(0)
+	println("[main] Explicitly pinned to core 0 using machine.LockCore()")
+	println()
+
+	// Start a goroutine pinned to core 1
+	go core1Worker()
+
+	// Start a goroutine using standard LockOSThread
+	go standardLockWorker()
+
+	// Start an unpinned goroutine (can run on either core)
+	go unpinnedWorker()
+
+	// Main loop on core 0
+	for i := 0; i < 10; i++ {
+		println("[main] loop", i, "on CPU", machine.CurrentCore())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	// Unpin and let main run on any core
+	machine.UnlockCore()
+	println()
+	println("[main] Unpinned using machine.UnlockCore()")
+
+	// Continue running for a bit to show potential migration
+	for i := 0; i < 5; i++ {
+		println("[main] unpinned loop on CPU", machine.CurrentCore())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	println()
+	println("Example complete!")
+}
+
+// Worker function that pins to core 1 using explicit core selection
+func core1Worker() {
+	// Pin this goroutine to core 1 explicitly
+	machine.LockCore(1)
+	println("[core1-worker] Worker pinned to core 1 using machine.LockCore()")
+
+	for i := 0; i < 10; i++ {
+		println("[core1-worker] loop", i, "on CPU", machine.CurrentCore())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	println("[core1-worker] Finished")
+}
+
+// Worker function that uses standard Go LockOSThread()
+func standardLockWorker() {
+	// Pin this goroutine to whichever core it starts on
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+
+	core := machine.CurrentCore()
+	println("[std-lock-worker] Worker locked using runtime.LockOSThread()")
+	println("[std-lock-worker] Running on core:", core)
+
+	for i := 0; i < 10; i++ {
+		println("[std-lock-worker] loop", i, "on CPU", machine.CurrentCore())
+		time.Sleep(600 * time.Millisecond)
+	}
+
+	println("[std-lock-worker] Finished")
+}
+
+// Worker function that is not pinned (can run on any core)
+func unpinnedWorker() {
+	println("[unpinned-worker] Starting")
+
+	for i := 0; i < 10; i++ {
+		cpu := machine.CurrentCore()
+		println("[unpinned-worker] loop", i, "on CPU", cpu)
+		time.Sleep(700 * time.Millisecond)
+
+		// Yield to potentially migrate to another core
+		runtime.Gosched()
+	}
+
+	println("[unpinned-worker] Finished")
+}

src/internal/task/task.go

@@ -29,6 +29,14 @@ type Task struct {
 	// since it falls into the padding of the FipsIndicator bit above.
 	RunState uint8
 
+	// Affinity specifies which CPU core this task should run on.
+	// -1 means no affinity (can run on any core)
+	// 0, 1, etc. means pinned to that specific core
+	// To be used ONLY with the "cores" scheduler.
+	// By default, all goroutines are unpinned (Affinity = -1)
+	// Pinning takes effect at the next scheduling point (e.g., after time.Sleep(), channel operations, or runtime.Gosched())
+	Affinity int8
+
 	// DeferFrame stores a pointer to the (stack allocated) defer frame of the
 	// goroutine that is used for the recover builtin.
 	DeferFrame unsafe.Pointer

src/machine/machine_rp2_cores.go

@@ -0,0 +1,57 @@
+//go:build (rp2040 || rp2350) && scheduler.cores
+
+package machine
+
+const numCPU = 2 // RP2040 and RP2350 both have 2 cores
+
+// LockCore sets the affinity for the current goroutine to the specified core.
+// This does not immediately migrate the goroutine; migration occurs at the next
+// scheduling point. See machine_rp2.go for full documentation.
+// Important: LockCore sets the affinity but does not immediately migrate the
+// goroutine to the target core. The actual migration happens at the next
+// scheduling point (e.g., channel operation, time.Sleep, or Gosched). After
+// that point, the goroutine will wait in the target core's queue if that core
+// is busy running another goroutine.
+//
+// To avoid potential blocking on a busy core, consider calling LockCore in an
+// init function before any other goroutines have started. This guarantees the
+// target core is available.
+//
+// This is useful for:
+//   - Isolating time-critical operations to a dedicated core
+//   - Improving cache locality for performance-sensitive code
+//   - Exclusive access to core-local resources
+//
+// Warning: Pinning goroutines can lead to load imbalance. The goroutine will
+// wait in the specified core's queue even if other cores are idle. If a
+// long-running goroutine occupies the target core, LockCore may appear to
+// block indefinitely (until the next scheduling point on the target core).
+//
+// Valid core values are 0 and 1. Panics if core is out of range.
+//
+// Only available on RP2040 and RP2350 with the "cores" scheduler.
+func LockCore(core int) {
+	if core < 0 || core >= numCPU {
+		panic("machine: core out of range")
+	}
+	machineLockCore(core)
+}
+
+// UnlockCore unpins the calling goroutine, allowing it to run on any available core.
+// This undoes a previous call to LockCore.
+//
+// After calling UnlockCore, the scheduler is free to schedule the goroutine on
+// any core for automatic load balancing.
+//
+// Only available on RP2040 and RP2350 with the "cores" scheduler.
+func UnlockCore() {
+	machineUnlockCore()
+}
+
+// Internal functions implemented in runtime/scheduler_cores.go
+//
+//go:linkname machineLockCore runtime.machineLockCore
+func machineLockCore(core int)
+
+//go:linkname machineUnlockCore runtime.machineUnlockCore
+func machineUnlockCore()

src/machine/machine_rp2_nocores.go

@@ -0,0 +1,15 @@
+//go:build (rp2040 || rp2350) && !scheduler.cores
+
+package machine
+
+// LockCore is not available without the cores scheduler.
+// This is a stub that panics.
+func LockCore(core int) {
+	panic("machine.LockCore: not available without scheduler.cores")
+}
+
+// UnlockCore is not available without the cores scheduler.
+// This is a stub that panics.
+func UnlockCore() {
+	panic("machine.UnlockCore: not available without scheduler.cores")
+}

src/runtime/runtime.go

@@ -98,14 +98,23 @@ func os_sigpipe() {
 }
 
 // LockOSThread wires the calling goroutine to its current operating system thread.
-// Stub for now
+// On microcontrollers with multiple cores (e.g., RP2040/RP2350), this pins the
+// goroutine to the core it's currently running on.
+// With the "cores" scheduler on RP2040/RP2350, this pins the goroutine to the
+// core it's currently running on. The pinning takes effect at the next
+// scheduling point (e.g., channel operation, time.Sleep, or Gosched).
 // Called by go1.18 standard library on windows, see https://github.com/golang/go/issues/49320
 func LockOSThread() {
+	lockOSThreadImpl()
 }
 
 // UnlockOSThread undoes an earlier call to LockOSThread.
-// Stub for now
+// On microcontrollers with multiple cores, this unpins the goroutine, allowing
+// it to run on any available core.
+// With the "cores" scheduler, this unpins the goroutine, allowing it to run on
+// any available core.
 func UnlockOSThread() {
+	unlockOSThreadImpl()
 }
 
 // KeepAlive makes sure the value in the interface is alive until at least the

src/runtime/scheduler_cooperative.go

@@ -261,6 +261,16 @@ func unlockAtomics(mask interrupt.State) {
 	interrupt.Restore(mask)
 }
 
+// lockOSThreadImpl is a no-op for the cooperative scheduler (single-threaded).
+func lockOSThreadImpl() {
+	// Single-threaded, nothing to do.
+}
+
+// unlockOSThreadImpl is a no-op for the cooperative scheduler (single-threaded).
+func unlockOSThreadImpl() {
+	// Single-threaded, nothing to do.
+}
+
 func printlock() {
 	// nothing to do
 }