ACE Help
========
This module emulates instructions for processors that do not have them.

Currently this emulates:

SWP, SWPB    : swap commands (useful for later hardware eg Raspberry Pi 3/4)
UDIV, SDIV   : divide commands
-See file ARMChipL for the full list


Q and GE Flags On Older Processors
==================================
Some instructions set Q or GE flags and older processors do not allow this
to happen by clearing any unknown flags.

An internal CPSR is used to store these values in ACE.

Instead of MSR commands, you can access this internal CPSR using the following instructons:

Simple:
MRC CP2,0,Rd,0,0          : Read CPSR where Rd is the destination register
MCR CP2,0,Rd,0,0          : Write CPSR where Rd stores the entire CPSR

Advanced:
MCR CP2,%0sf,Rd,0,0,%0cx  : Write CPSR. Only cxsf parts where bits set.
                            If all cxsf are zero write entire CPSR
MCR CP2,%0sf,H,L,Shf,%1cx : Write CPSR with immediate. Immediate is as MSR
                            immediate instruction format: &HL ROR (Shf<<1)
                            If all cxsf are zero write entire CPSR

The above commands will use your live CPSR and merge the internal Q and GE
flags in one instruction. Only real CPSR and Q and GE bits can be set.
Reserved bits will be set to zero. When writing to the CPSR you are writing to
the real CPSR and the internal one at the same time.

The SWI ACE_VforMSR will return with V set if you can use MSR commands. You
should call the X version of this SWI by its number only. This allows the
following code to work on all processors even if ACE is not running:

SWI &E0082 ; ACE_VforMSR, sets V if can use MSR/MRS or if SWI does not exist
             R0 may be corrupted, all other registers are preserved
MCRVC CPSR,R10
MSRVS CP2,0,R10,0,0

It would be recommended to use a function or macro to implement a read and
write version of this in the assembler you use.


Register Your Own Commands
==========================
---
SWI "ACE_Register"

Entry: R0 Instruction mask (see *1)
       R1 Instruction value (see *1)
       R2 Pointer to handler code (see *2)

Exit:  R0 Handler number (needed to deregister)
       V  Set if error

---

SWI "ACE_Deregister"

Entry: R0 Handler number

---

Instruction Mask and Value (*1)

Mask bits are set to tell ACE which bits to check against the encoding. Set mask bits to one where value is fixed (either zero or one but never changes). In the example below bits 27 to 16 and 11 to 4 are fixed. The mask has these bits set.

Set value bit to ones where fixed in decoding, otherwise zero. The bits are the same as the encoding with anything that can change set to zero. So condition, Rd and Rn are all zero bits, other bits are set to the same as the encoding.

If you wish to intercept the following instruction decoding:
Bit:      31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Encoding: -Condition-  0  1  0  1  0  1  0  1  0  1  0  1 -----Rd----  0  1 0 1 0 1 0 1 --Rn---
Mask:      0  0  0  0  1  1  1  1  1  1  1  1  1  1  1  1  0  0  0  0  1  1 1 1 1 1 1 1 0 0 0 0
Value:     0  0  0  0  0  1  0  1  0  1  0  1  0  1  0  1  0  0  0  0  1  1 1 1 1 1 1 1 0 0 0 0

Simple Table

Encoding Bit  Can change    Always 1    Always 0
Mask Bit          0             1          1
Value Bit         0             1          0

---

Hander Code

Your code can be called at any time. It must not be in application memory or any other memory location that can be paged in or out. It is recommended to be in the module area.

Entry: R0 Instruction encoding of the undefined instruction
       R1 Table of registers plus CPSR (*3)
       R2 CPSR for convenience

Exit:  R0 Preserve
       R1 Preserve
       R2 Preserve
       R3 Set to:
           0 Failed to run instruction.
             Registers in table of registers must be preserved.
           1 Completed instruction.
             Registers in table of registers plus CPSR flags have been updated.
           2 Completed instruction.
             Registers in table of registers plus the entire CPSR updated.

Table of registers

       +0   R0
       +4   R1
       +8   R2
       +12  R3
       +16  R4
       +20  R5
       +24  R6
       +28  R7
       +32  R8
       +36  R9
       +40  R10
       +44  R11
       +48  R12
       +52  R13
       +56  R14
       +60  R15
       +64  CPSR