Add goroutine core affinity support for RP2040/RP2350 systems

- Introduced support for CPU core pinning and affinity for tasks and goroutines.
- Updated the scheduler to respect affinity constraints with separate queues for pinned and shared tasks.
- Added new runtime API functions `LockToCore`, `UnlockFromCore`, `GetAffinity`, and `CurrentCPU`.
- Example program demonstrates core pinning and unpinned execution behavior.

Author: amken3d

src/examples/core-pinning/main.go

@@ -0,0 +1,80 @@
+// 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 (
+	"runtime"
+	"time"
+)
+
+func main() {
+	println("=== Core Pinning Example ===")
+	println("Number of CPU cores:", runtime.NumCPU())
+	println("Main starting on core:", runtime.CurrentCPU())
+	println()
+
+	// Pin main goroutine to core 0
+	runtime.LockToCore(0)
+	println("Main pinned to core:", runtime.GetAffinity())
+	println()
+
+	// Start a goroutine pinned to core 1
+	go core1Worker()
+
+	// Start an unpinned goroutine (can run on either core)
+	go unpinnedWorker()
+
+	// Main loop on core 0
+	for i := 0; i < 10; i++ {
+		println("Core 0 (main):", i, "on CPU", runtime.CurrentCPU())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	// Unpin and let main run on any core
+	runtime.UnlockFromCore()
+	println()
+	println("Main unpinned, affinity:", runtime.GetAffinity())
+
+	// Continue running for a bit to show migration
+	for i := 0; i < 5; i++ {
+		println("Unpinned main on CPU", runtime.CurrentCPU())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	println()
+	println("Example complete!")
+}
+
+// Worker function that runs on core 1
+func core1Worker() {
+	// Pin this goroutine to core 1
+	runtime.LockToCore(1)
+	println("Worker pinned to core:", runtime.GetAffinity())
+
+	for i := 0; i < 10; i++ {
+		println("  Core 1 (worker):", i, "on CPU", runtime.CurrentCPU())
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	println("  Core 1 worker finished")
+}
+
+// Worker function that is not pinned (can run on any core)
+func unpinnedWorker() {
+	println("Unpinned worker starting, affinity:", runtime.GetAffinity())
+
+	for i := 0; i < 10; i++ {
+		cpu := runtime.CurrentCPU()
+		println("    Unpinned worker:", 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/runtime/scheduler_cores.go

@@ -22,8 +22,9 @@ var secondaryCoresStarted bool
 var cpuTasks [numCPU]*task.Task
 
 var (
-	sleepQueue *task.Task
-	runqueue   task.Queue
+	sleepQueue     *task.Task
+	runqueueShared task.Queue         // For unpinned tasks (affinity = -1)
+	runqueueCore   [numCPU]task.Queue // Per-core queues for pinned tasks
 )
 
 func deadlock() {
@@ -39,8 +40,14 @@ func scheduleTask(t *task.Task) {
 	switch t.RunState {
 	case task.RunStatePaused:
 		// Paused, state is saved on the stack.
-		// Add it to the runqueue...
-		runqueue.Push(t)
+		// Route to appropriate queue based on affinity.
+		if t.Affinity >= 0 && t.Affinity < numCPU {
+			// Pinned to specific core
+			runqueueCore[t.Affinity].Push(t)
+		} else {
+			// Not pinned, use shared queue
+			runqueueShared.Push(t)
+		}
 		// ...and wake up a sleeping core, if there is one.
 		// (If all cores are already busy, this is a no-op).
 		schedulerWake()
@@ -86,7 +93,15 @@ func addSleepTask(t *task.Task, wakeup timeUnit) {
 
 func Gosched() {
 	schedulerLock.Lock()
-	runqueue.Push(task.Current())
+	t := task.Current()
+
+	// Respect affinity when re-queueing.
+	if t.Affinity >= 0 && t.Affinity < numCPU {
+		runqueueCore[t.Affinity].Push(t)
+	} else {
+		runqueueShared.Push(t)
+	}
+
 	task.PauseLocked()
 }
 
@@ -95,6 +110,53 @@ func NumCPU() int {
 	return numCPU
 }
 
+// CurrentCPU returns the current CPU core number.
+// On RP2040/RP2350, this returns 0 or 1.
+func CurrentCPU() int {
+	return int(currentCPU())
+}
+
+// LockToCore pins the current goroutine to the specified CPU core.
+// Use core = -1 to unpin (allow running on any core).
+// Use core = 0 or 1 to pin to a specific core.
+// Panics if core is invalid (not -1, 0, or 1 on RP2040/RP2350).
+func LockToCore(core int) {
+	if core < -1 || core >= numCPU {
+		panic("runtime: invalid core number")
+	}
+
+	schedulerLock.Lock()
+	t := task.Current()
+	if t != nil {
+		t.Affinity = int8(core)
+	}
+	schedulerLock.Unlock()
+}
+
+// UnlockFromCore unpins the current goroutine, allowing it to run on any core.
+// This is equivalent to LockToCore(-1).
+func UnlockFromCore() {
+	schedulerLock.Lock()
+	t := task.Current()
+	if t != nil {
+		t.Affinity = -1
+	}
+	schedulerLock.Unlock()
+}
+
+// GetAffinity returns the CPU core affinity of the current goroutine.
+// Returns -1 if not pinned, or 0/1 if pinned to a specific core.
+func GetAffinity() int {
+	schedulerLock.Lock()
+	t := task.Current()
+	affinity := -1
+	if t != nil {
+		affinity = int(t.Affinity)
+	}
+	schedulerLock.Unlock()
+	return affinity
+}
+
 func addTimer(tn *timerNode) {
 	schedulerLock.Lock()
 	timerQueueAdd(tn)
@@ -110,7 +172,7 @@ func removeTimer(t *timer) *timerNode {
 }
 
 func schedulerRunQueue() *task.Queue {
-	return &runqueue
+	return &runqueueShared
 }
 
 // Pause the current task for a given time.
@@ -160,9 +222,33 @@ func run() {
 }
 
 func scheduler(_ bool) {
+	currentCore := int(currentCPU())
+
 	for mainExited.Load() == 0 {
 		// Check for ready-to-run tasks.
-		if runnable := runqueue.Pop(); runnable != nil {
+		// First, try to get a task pinned to this core.
+		var runnable *task.Task
+		if currentCore < numCPU {
+			runnable = runqueueCore[currentCore].Pop()
+		}
+
+		// If no pinned tasks, try the shared queue.
+		if runnable == nil {
+			runnable = runqueueShared.Pop()
+		}
+
+		if runnable != nil {
+			// Verify affinity constraint (sanity check).
+			if runnable.Affinity >= 0 && runnable.Affinity != int8(currentCore) {
+				// Shouldn't happen, but put it back on correct queue.
+				if runnable.Affinity < numCPU {
+					runqueueCore[runnable.Affinity].Push(runnable)
+				} else {
+					runqueueShared.Push(runnable)
+				}
+				continue
+			}
+
 			// Resume it now.
 			setCurrentTask(runnable)
 			runnable.RunState = task.RunStateRunning
@@ -183,6 +269,19 @@ func scheduler(_ bool) {
 				sleepQueue = sleepQueue.Next
 				sleepingTask.Next = nil
 
+				// Check affinity before running.
+				if sleepingTask.Affinity >= 0 && sleepingTask.Affinity != int8(currentCore) {
+					// Task is pinned to a different core, re-queue it.
+					sleepingTask.RunState = task.RunStatePaused
+					if sleepingTask.Affinity < numCPU {
+						runqueueCore[sleepingTask.Affinity].Push(sleepingTask)
+					} else {
+						runqueueShared.Push(sleepingTask)
+					}
+					schedulerWake()
+					continue
+				}
+
 				// Run it now.
 				setCurrentTask(sleepingTask)
 				sleepingTask.RunState = task.RunStateRunning