+;;
+;;
+;; Atomic integer operations for the Renesas / SuperH SH CPUs.
+;;
+;; On single-core systems there can only be one execution context running
+;; at a given point in time. This allows the usage of rewindable atomic
+;; sequences, which effectively emulate locked-load / conditional-store
+;; operations.
+;; When an execution context is interrupted while it is an atomic
+;; sequence, the interrupted context's PC is rewound to the beginning of
+;; the atomic sequence by the interrupt / exception handling code, before
+;; transferring control to another execution context. This is done by
+;; something like...
+;;
+;; if (interrupted_context_in_atomic_sequence
+;; && interrupted_pc < atomic_exitpoint)
+;; interrupted_pc = atomic_entrypoint;
+;;
+;; This method is also known as gUSA ("g" User Space Atomicity) and the
+;; Linux kernel for SH3/SH4 implements support for such software
+;; atomic sequences. However, it can also be implemented in freestanding
+;; environments.
+;;
+;; For this the following atomic sequence ABI is used.
+;;
+;; r15 >= 0: Execution context is not in an atomic sequence.
+;;
+;; r15 < 0: Execution context is in an atomic sequence and r15
+;; holds the negative byte length of the atomic sequence.
+;; In this case the following applies:
+;;
+;; r0: PC of the first instruction after the atomic
+;; write-back instruction (exit point).
+;; The entry point PC of the atomic sequence can be
+;; determined by doing r0 + r15.
+;;
+;; r1: Saved r15 stack pointer before entering the
+;; atomic sequence.
+;;
+;; An example atomic add sequence would look like:
+;;
+;; mova .Lend,r0 ! .Lend must be 4-byte aligned.
+;; mov r15,r1
+;; .align 2 ! Insert aligning nop if needed.
+;; mov #(.Lstart - .Lend),r15 ! Enter atomic sequence
+;;.Lstart:
+;; mov.l @r4,r2 ! read value
+;; add r2,r5 ! modify value
+;; mov.l r5,@r4 ! write-back
+;;.Lend:
+;; mov r1,r15 ! Exit atomic sequence
+;; ! r2 holds the previous value.
+;; ! r5 holds the new value.
+;;
+;; Notice that due to the restrictions of the mova instruction, the .Lend
+;; label must always be 4-byte aligned. Aligning the .Lend label would
+;; potentially insert a nop after the write-back instruction which could
+;; make the sequence to be rewound, although it has already passed the
+;; write-back instruction. This would make it execute twice.
+;; For correct operation the atomic sequences must not be rewound after
+;; they have passed the write-back instruction.
+;;
+;; The current implementation is limited to QImode, HImode and SImode
+;; atomic operations. DImode operations could also be implemented but
+;; would require some ABI modifications to support multiple-instruction
+;; write-back. This is because SH1/SH2/SH3/SH4 does not have a DImode
+;; store instruction. DImode stores must be split into two SImode stores.
+;;
+;; For some operations it would be possible to use insns with an immediate
+;; operand such as add #imm,Rn. However, since the original value before
+;; the operation also needs to be available, this is not so handy.