Create HW spinlock usage examples both assembly/C in open-pru/academy

[pratheesh-ti]

This is needed to address queries like https://e2e.ti.com/support/microcontrollers/arm-based-microcontrollers-group/arm-based-microcontrollers/f/arm-based-microcontrollers-forum/1626049/am6442-pru-accessing-hw-spinlocks-with-__xin-__xout
;INT_SPIN_XID - XID for Local spinlock
INT_SPIN_XID .set 144
SPINLOCK_ID .set 0 ; As an example
;****************************************************************************
;
; Macro: M_SPINLOCK_ACQUIRE
;
; Acquire spinlock and busy-wait until successful
;
; PeakCycles:
; Best case: 3 cycles (if spinlock available immediately)
; Worst case: unbounded (busy-wait until lock acquired)
;
; Invokes:
; None
;
; Registers:
; r1.b0 - Input: spinlock number (set to SPINLOCK_ID)
; r1.b3 - Output: acquisition status (0=failed, 1=acquired)
;
; PseudoCode:
; (start code)
; r1.b0 = SPINLOCK_ID
; do {
; xin from INT_SPIN_XID accelerator
; check acquired status in r1.b3 bit0
; } while (not acquired)
; (end code)
;
; Parameters:
; None (uses SPINLOCK_ID constant)
;
; Returns:
; None (spinlock acquired on exit)
;
; Note:
; This is a blocking busy-wait spinlock. R1.b0 contains the spinlock ID,
; R1.b3 receives the status. On successful acquisition, R1.b3 bit 0 is set to 1.
;
; See Also:
; M_SPINLOCK_RELEASE
;
;****************************************************************************
M_SPINLOCK_ACQUIRE .macro
LDI R1.b0, SPINLOCK_ID ; can range from 0-63, fixed in PRU firmware
$1:
XIN INT_SPIN_XID, &R1.b3, 1
QBBC $1, R1.b3, 0
.endm

;****************************************************************************
;
; Macro: M_SPINLOCK_RELEASE
;
; Release spinlock
;
; PeakCycles:
; 2 cycle
;
; Invokes:
; None
;
; Registers:
; R1.b0 - Input: spinlock number (set to SPINLOCK_ID)
; R1.b3 - Used for XOUT operation
;
; PseudoCode:
; (start code)
; r1.b0 = SPINLOCK_ID
; xout R1.b3 to spinlock accelerator to release
; (end code)
;
; Parameters:
; None
;
; Returns:
; None
;
; Note:
; Must be called after M_SPINLOCK_ACQUIRE. The XOUT operation uses R1.b3
; to release the spinlock that was acquired with the ID in R1.b0.
;
; See Also:
; M_SPINLOCK_ACQUIRE
;
;****************************************************************************
M_SPINLOCK_RELEASE .macro
XOUT INT_SPIN_XID, &R1.b3, 1
.endm

[nsaulnier-ti]

Example for C code:

main.c

spinlock.txt

NOTE!! the attached spinlock.txt file should actually be spinlock.asm, but github won't allow me to attach .asm files.