Refactored based on Elias' comments

- Dropped CurrentCPU
- Dropped GetAffinity
- Renamed LockToCore to LockCore to mimic LockOSThread naming.
- Updated examples program

Author: amken3d

src/examples/core-pinning/main.go

@@ -1,80 +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 starting on core:", runtime.CurrentCPU())
+	println("[main] Main starting on core:", machine.CurrentCore())
 	println()
 
-	// Pin main goroutine to core 0
-	runtime.LockToCore(0)
-	println("Main pinned to core:", runtime.GetAffinity())
+	// 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("Core 0 (main):", i, "on CPU", runtime.CurrentCPU())
+		println("[main] loop", i, "on CPU", machine.CurrentCore())
 		time.Sleep(500 * time.Millisecond)
 	}
 
 	// Unpin and let main run on any core
-	runtime.UnlockFromCore()
+	machine.UnlockCore()
 	println()
-	println("Main unpinned, affinity:", runtime.GetAffinity())
+	println("[main] Unpinned using machine.UnlockCore()")
 
-	// Continue running for a bit to show migration
+	// Continue running for a bit to show potential migration
 	for i := 0; i < 5; i++ {
-		println("Unpinned main on CPU", runtime.CurrentCPU())
+		println("[main] unpinned loop on CPU", machine.CurrentCore())
 		time.Sleep(500 * time.Millisecond)
 	}
 
 	println()
 	println("Example complete!")
 }
 
-// Worker function that runs on core 1
+// Worker function that pins to core 1 using explicit core selection
 func core1Worker() {
-	// Pin this goroutine to core 1
-	runtime.LockToCore(1)
-	println("Worker pinned to core:", runtime.GetAffinity())
+	// 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("  Core 1 (worker):", i, "on CPU", runtime.CurrentCPU())
+		println("[core1-worker] loop", i, "on CPU", machine.CurrentCore())
 		time.Sleep(500 * time.Millisecond)
 	}
 
-	println("  Core 1 worker finished")
+	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, affinity:", runtime.GetAffinity())
+	println("[unpinned-worker] Starting")
 
 	for i := 0; i < 10; i++ {
-		cpu := runtime.CurrentCPU()
-		println("    Unpinned worker:", i, "on CPU", cpu)
+		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")
+	println("[unpinned-worker] Finished")
 }

src/machine/machine_rp2_cores.go

@@ -0,0 +1,26 @@
+//go:build (rp2040 || rp2350) && scheduler.cores
+
+package machine
+
+const numCPU = 2 // RP2040 and RP2350 both have 2 cores
+
+// LockCore implementation for the cores scheduler.
+func LockCore(core int) {
+	if core < 0 || core >= numCPU {
+		panic("machine: core out of range")
+	}
+	machineLockCore(core)
+}
+
+// UnlockCore implementation for 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,18 @@ 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.
 // 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.
 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
 }

src/runtime/scheduler_cores.go

@@ -110,21 +110,18 @@ 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")
-	}
+//
+// Warning: Pinning goroutines can lead to load imbalance. The goroutine will
+// wait in the specified core's queue even if other cores are idle. Use this
+// feature carefully and only when you need explicit core affinity.
+//
+// Valid core values are 0 and 1. Panics if core is out of range.
+//
 
+// machineLockCore pins the current goroutine to the specified CPU core.
+// This is called by machine.LockCore() on RP2040/RP2350.
+// It does not validate the core number - validation is done in machine package.
+func machineLockCore(core int) {
 	schedulerLock.Lock()
 	t := task.Current()
 	if t != nil {
@@ -133,9 +130,9 @@ func LockToCore(core int) {
 	schedulerLock.Unlock()
 }
 
-// UnlockFromCore unpins the current goroutine, allowing it to run on any core.
-// This is equivalent to LockToCore(-1).
-func UnlockFromCore() {
+// machineUnlockCore unpins the current goroutine.
+// This is called by machine.UnlockCore() on RP2040/RP2350.
+func machineUnlockCore() {
 	schedulerLock.Lock()
 	t := task.Current()
 	if t != nil {
@@ -144,17 +141,16 @@ func UnlockFromCore() {
 	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
+// lockOSThreadImpl implements LockOSThread for the cores scheduler.
+// It pins the current goroutine to whichever core it's currently running on.
+func lockOSThreadImpl() {
+	core := int(currentCPU())
+	machineLockCore(core)
+}
+
+// unlockOSThreadImpl implements UnlockOSThread for the cores scheduler.
+func unlockOSThreadImpl() {
+	machineUnlockCore()
 }
 
 func addTimer(tn *timerNode) {

src/runtime/scheduler_none.go

@@ -85,6 +85,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
 }

src/runtime/scheduler_threads.go

@@ -157,3 +157,13 @@ func lockAtomics() interrupt.State {
 func unlockAtomics(mask interrupt.State) {
 	atomicsLock.Unlock()
 }
+
+// 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.
+}