Arithmetic instructions

Document conventions

Notation: ``Rd, Rm, Rn`` denote ARM registers R0-R7. ``immN`` denotes an immediate

value having a width of N bits e.g. ``imm8``, ``imm3``. ``carry`` denotes

the carry condition flag, ``not(carry)`` denotes its complement. In the case of instructions

with more than one register argument, it is permissible for some to be identical. For example

the following will add the contents of R0 to itself, placing the result in R0:

* add(r0, r0, r0)

Arithmetic instructions affect the condition flags except where stated.

Addition

* add(Rdn, imm8) ``Rdn = Rdn + imm8``

* add(Rd, Rn, imm3) ``Rd = Rn + imm3``

* add(Rd, Rn, Rm) ``Rd = Rn +Rm``

* adc(Rd, Rn) ``Rd = Rd + Rn + carry``

Subtraction

* sub(Rdn, imm8) ``Rdn = Rdn - imm8``

* sub(Rd, Rn, imm3) ``Rd = Rn - imm3``

* sub(Rd, Rn, Rm) ``Rd = Rn - Rm``

* sbc(Rd, Rn) ``Rd = Rd - Rn - not(carry)``

Negation

* neg(Rd, Rn) ``Rd = -Rn``

Multiplication and division

* mul(Rd, Rn) ``Rd = Rd * Rn``

This produces a 32 bit result with overflow lost. The result may be treated as

signed or unsigned according to the definition of the operands.

* sdiv(Rd, Rn, Rm) ``Rd = Rn / Rm``

* udiv(Rd, Rn, Rm) ``Rd = Rn / Rm``

These functions perform signed and unsigned division respectively. Condition flags

are not affected.

Comparison instructions

These perform an arithmetic or logical instruction on two arguments, discarding the result

but setting the condition flags. Typically these are used to test data values without changing

them prior to executing a conditional branch.

Document conventions

Notation: ``Rd, Rm, Rn`` denote ARM registers R0-R7. ``imm8`` denotes an immediate

value having a width of 8 bits.

The Application Program Status Register (APSR)

This contains four bits which are tested by the conditional branch instructions. Typically a

conditional branch will test multiple bits, for example ``bge(LABEL)``. The meaning of

condition codes can depend on whether the operands of an arithmetic instruction are viewed as

signed or unsigned integers. Thus ``bhi(LABEL)`` assumes unsigned numbers were processed while

``bgt(LABEL)`` assumes signed operands.

APSR Bits

* Z (zero)

This is set if the result of an operation is zero or the operands of a comparison are equal.

* N (negative)

Set if the result is negative.

* C (carry)

An addition sets the carry flag when the result overflows out of the MSB, for example adding

0x80000000 and 0x80000000. By the nature of two's complement arithmetic this behaviour is reversed

on subtraction, with a borrow indicated by the carry bit being clear. Thus 0x10 - 0x01 is executed

as 0x10 + 0xffffffff which will set the carry bit.

* V (overflow)

The overflow flag is set if the result, viewed as a two's compliment number, has the "wrong" sign

in relation to the operands. For example adding 1 to 0x7fffffff will set the overflow bit because

the result (0x8000000), viewed as a two's complement integer, is negative. Note that in this instance

the carry bit is not set.

Comparison instructions

These set the APSR (Application Program Status Register) N (negative), Z (zero), C (carry) and V

(overflow) flags.

* cmp(Rn, imm8) ``Rn - imm8``

* cmp(Rn, Rm) ``Rn - Rm``

* cmn(Rn, Rm) ``Rn + Rm``

* tst(Rn, Rm) ``Rn & Rm``

Conditional execution

The ``it`` and ``ite`` instructions provide a means of conditionally executing from one to four subsequent

instructions without the need for a label.

* it(<condition>) If then

Execute the next instruction if <condition> is true:

::

* ite(<condition>) If then else

If <condtion> is true, execute the next instruction, otherwise execute the

subsequent one. Thus:

::

This may be extended to control the execution of upto four subsequent instructions: it[x[y[z]]]

where x,y,z=t/e; e.g. itt, itee, itete, ittte, itttt, iteee, etc.

Assembler Directives

Labels

* label(INNER1)

This defines a label for use in a branch instruction. Thus elsewhere in the code a ``b(INNER1)``

will cause execution to continue with the instruction after the label directive.

Defining inline data

The following assembler directives facilitate embedding data in an assembler code block.

* data(size, d0, d1 .. dn)

The data directive creates n array of data values in memory. The first argument specifies the

size in bytes of the subsequent arguments. Hence the first statement below will cause the

assembler to put three bytes (with values 2, 3 and 4) into consecutive memory locations

while the second will cause it to emit two four byte words.

::

Data values longer than a single byte are stored in memory in little-endian format.

* align(nBytes)

Align the following instruction to an nBytes value. ARM Thumb-2 instructions must be two

byte aligned, hence it's advisable to issue ``align(2)`` after ``data`` directives and

prior to any subsequent code. This ensures that the code will run irrespective of the

size of the data array.

Floating Point instructions

These instructions support the use of the ARM floating point coprocessor

(on platforms such as the Pyboard which are equipped with one). The FPU

has 32 registers known as ``s0-s31`` each of which can hold a single

precision float. Data can be passed between the FPU registers and the

ARM core registers with the ``vmov`` instruction.

Note that MicroPython doesn't support passing floats to

assembler functions, nor can you put a float into ``r0`` and expect a

reasonable result. There are two ways to overcome this. The first is to

use arrays, and the second is to pass and/or return integers and convert

to and from floats in code.

Document conventions

Notation: ``Sd, Sm, Sn`` denote FPU registers, ``Rd, Rm, Rn`` denote ARM core

registers. The latter can be any ARM core register although registers

``R13-R15`` are unlikely to be appropriate in this context.

Arithmetic

* vadd(Sd, Sn, Sm) ``Sd = Sn + Sm``

* vsub(Sd, Sn, Sm) ``Sd = Sn - Sm``

* vneg(Sd, Sm) ``Sd = -Sm``

* vmul(Sd, Sn, Sm) ``Sd = Sn * Sm``

* vdiv(Sd, Sn, Sm) ``Sd = Sn / Sm``

* vsqrt(Sd, Sm) ``Sd = sqrt(Sm)``

Registers may be identical: ``vmul(S0, S0, S0)`` will execute ``S0 = S0*S0``

Move between ARM core and FPU registers

* vmov(Sd, Rm) ``Sd = Rm``

* vmov(Rd, Sm) ``Rd = Sm``

The FPU has a register known as FPSCR, similar to the ARM core's APSR, which stores condition

codes plus other data. The following instructions provide access to this.

* vmrs(APSR\_nzcv, FPSCR)

Move the floating-point N, Z, C, and V flags to the APSR N, Z, C, and V flags.

This is done after an instruction such as an FPU

comparison to enable the condition codes to be tested by the assembler

code. The following is a more general form of the instruction.

* vmrs(Rd, FPSCR) ``Rd = FPSCR``

Move between FPU register and memory

* vldr(Sd, [Rn, offset]) ``Sd = [Rn + offset]``

* vstr(Sd, [Rn, offset]) ``[Rn + offset] = Sd``

Where ``[Rn + offset]`` denotes the memory address obtained by adding Rn to the offset. This

is specified in bytes. Since each float value occupies a 32 bit word, when accessing arrays of

floats the offset must always be a multiple of four bytes.

Data Comparison

* vcmp(Sd, Sm)

Compare the values in Sd and Sm and set the FPU N, Z,

C, and V flags. This would normally be followed by ``vmrs(APSR_nzcv, FPSCR)``

to enable the results to be tested.

Convert between integer and float

* vcvt\_f32\_s32(Sd, Sm) ``Sd = float(Sm)``

* vcvt\_s32\_f32(Sd, Sm) ``Sd = int(Sm)``