chore: clarify comments

Author: mikesmitty

src/runtime/runtime_rp2350.go

@@ -18,9 +18,9 @@ const (
 
 // Due to hardware errata RP2350-E2 spinlocks are emulated in software as in pico-sdk.
 type spinLock struct {
-	// lock field must be first field so its address is the same as the struct address.
-	lock uint8
-	id   uint8
+	// state field must be first field so its address is the same as the struct address.
+	state  uint8
+	id     uint8
 	uint16 // Padding to prevent false sharing
 }
 
@@ -29,28 +29,28 @@ func (l *spinLock) Lock() {
 	// https://github.com/raspberrypi/pico-sdk/blob/2.2.0/src/rp2_common/hardware_sync_spin_lock/include/hardware/sync/spin_lock.h#L112
 
 	// r0 is automatically filled with the pointer value "l" here.
-	// We create a variable to allow access the lock byte and avoid a memory
-	// fault when accessing l.lock in assembly.
-	lock := &l.lock
-	_ = lock
+	// We create a variable to permit access to the state byte (l.state) and
+	// avoid a memory fault when accessing it in assembly.
+	state := &l.state
+	_ = state
 
-	// Set a loop start point
+	// Set the loop start point.
 	arm.Asm("1:")
-	// Exclusively load the state variable (l.lock) and put its value in r2.
+	// Exclusively load (lock) the state byte and put its value in r2.
 	arm.Asm("ldaexb r2, [r0]")
-	// Store the "locked" state value (1) into r1 to keep things moving.
+	// Set the r1 register to '1' for later use.
 	arm.Asm("movs r1, #1")
 	// Check if the lock was already taken (r2 != 0).
 	arm.Asm("cmp r2, #0")
-	// Jump back to "1:" if the lock is already held
+	// Jump back to the loop start ("1:") if the lock is already held.
 	arm.Asm("bne 1b")
 
-	// Attempt to store '1' into the lock address.
+	// Attempt to store '1' into the lock state byte.
 	// The return code (0 for success, 1 for failure) is placed in r2.
 	arm.Asm("strexb r2, r1, [r0]")
 	// Check if the result was successful (r2 == 0).
 	arm.Asm("cmp r2, #0")
-	// Jump back to "1:" if the lock was not acquired.
+	// Jump back to the loop start ("1:") if the lock was not acquired.
 	arm.Asm("bne 1b")
 
 	// Memory barrier to ensure everyone knows we're holding the lock now.
@@ -62,13 +62,13 @@ func (l *spinLock) Unlock() {
 	// https://github.com/raspberrypi/pico-sdk/blob/2.2.0/src/rp2_common/hardware_sync_spin_lock/include/hardware/sync/spin_lock.h#L197
 
 	// r0 is automatically filled with the pointer value l here.
-	// We create a variable to allow access the lock byte and avoid a memory
-	// fault when accessing l.lock in assembly.
-	lock := &l.lock
-	_ = lock
-	// Fill r1 with 0 and store it to the lock address in r0. stlb requires a
-	// register as a source so we can't use a literal 0 directly.
+	// We create a variable to permit access to the state byte (l.state) and
+	// avoid a memory fault when accessing it in assembly.
+	state := &l.state
+	_ = state
+	// Fill r1 with 0 and store it to the state byte address in r0. stlb
+	// requires a register as a source so we can't use a literal 0 directly.
 	arm.Asm("movs r1, #0")
-	// Release the pseudo-spinlock by writing 0 to and releasing l.lock.
+	// Release the pseudo-spinlock by writing 0 to and releasing l.state.
 	arm.Asm("stlb r1, [r0]")
 }