doc/range-limits.md

Immediate Range Limits in VIXL
==============================

VIXL's macro assembler tries to increase the range of branches and literal loads
automatically for you, but applications must still be aware of these extended
limits, and stay within them, in order to ensure valid code is generated.

In debug builds, assertions prevent exceeding these limits at run time. In
release builds, for performance reasons, the application is responsible for
staying within the limits.

You should decide what corrections should be applied in your application if it
exceeds these limits.

Terms
-----

**Bind** assigning an address to a label such that the instructions that refer
to the label can be assigned PC-relative offsets.

**Forward** a forward branch or load literal will refer to a location that will
be bound later in code generation, ie. at a higher address.

**Backward** a backward branch or load literal refers to a location that has
already been bound earlier in code generation, ie. at a lower address.

**Instruction range** the range of values that can be encoded in the instruction
to be generated. Outside the instruction range, additional instructions may be
generated to increase the range, branching further than would be possible in
one instruction, for example.

**Veneer** a sequence of additional instructions produced to increase the
instruction range.

**Adjusted PC** the PC including its architecturally-defined offset. In AArch32
T32, this is the current PC plus four bytes. In AArch64, there is no adjustment;
Adjusted PC is equal to PC.

AArch64
-------

### Branches

All instructions and targets must be aligned to the instruction size, four
bytes.

#### Unconditional immediate branches (`B`)

* Unconditional immediate branches have an instruction range of -134,217,728 to
+134,217,724 bytes from the current PC.
* No veneers are applied to unconditional immediate branches to extend their
instruction range.
* Callers can use the function `IsValidImmPCOffset(UncondBranchType, offset)` to
check `offset` (in units of instruction) is within the instruction range.

#### Conditional branches (`B.cond`) and compare-and-branch (`CBZ`, `CBNZ`)

* Conditional branch and compare-and-branch instructions have the same
instruction range.
* The instruction range is -1,048,576 to +1,048,574 bytes from the current PC.
* Veneers are applied to extend the range to -134,217,724 to +135,266,298 bytes
from the current PC.
  * Unconditional branch range minus one instruction backwards.
  * Unconditional branch range plus conditional branch range forwards.
* Callers can use the functions `IsValidImmPCOffset(CondBranchType, offset)` and
`IsValidImmPCOffset(CompareBranchType, offset)` to check `offset` (in units of
instruction) is within the instruction range.

#### Test-and-branch (`TBZ`, `TBNZ`)

* Test-and-branch instructions have an instruction range of -32,768 to 32,764
bytes from the current PC.
* Veneers are applied to extend the range to -134,217,728 to +135,299,062 bytes
from the current PC.
  * Unconditional branch range minus one instruction backwards.
  * Unconditional branch range plus test-and-branch range forwards.
* Callers can use the function `IsValidImmPCOffset(TestBranchType, offset)` to
check `offset` (in units of instruction) is within the instruction range.

### Literals

#### Compute PC-relative address (`ADR`)

* Compute PC-relative address instructions have an instruction range of
-1,048,576 to +1,048,575 bytes from the current PC.
* No veneers are applied to extend the instruction range.
* Callers can use `IsInt21(offset)` to check `offset` (in bytes) is within the
instruction range.

#### Load from PC-relative address (`LDR`)

* Load from PC-relative address instructions have an instruction range of
-1,048,576 to +1,048,572 bytes from the current PC. The offset must be four-byte
aligned.
* Automatically-placed literals (eg. those created by `Ldr(reg, literal_value)`)
will be emitted into code such that they are in range of the instructions that
refer to them.
* Veneers are not applied to manually-placed literals, ie. those created by
`Literal<T> x(value)` and emitted by `place()`.
* Callers can use `IsInt19(offset)` to check `offset` (in units of instruction)
is within the instruction range.

AArch32
-------

Limits stated in this section relate to the T32 instruction encodings only.

### Branches

#### Unconditional immediate branches (`B`)

* Unconditional immediate branches have an instruction range of -16,777,216 to
+16,777,214 bytes from the current adjusted PC.
* Veneers are applied to forward branches to extend them to an unlimited range.
* No veneers are applied to backward branches.

#### Conditional immediate branches (`B`)

* Conditional immediate branches have an instruction range of -1,048,576 to
+1,048,574 bytes from the current adjusted PC.
* Veneers are applied to forward branches to extend them to an unlimited range.
* Veneers are applied to backward branches to extend the range to that of
unconditional immediate branches, -16,777,216 bytes from the current adjusted
PC.

#### Compare and branch (`CBZ`, `CBNZ`)

* Compare and branch has an instruction range of 0 to +126 bytes from the
current adjusted PC.
* Veneers are applied to forward branches to extend them to an unlimited range.
* Veneers are applied to backward branches to extend the range to that of
unconditional immediate branches, -16,777,216 bytes from the current adjusted
PC.

### Literals

#### Compute/load PC-relative address (`ADR`, `LDR`)

* Compute and load PC-relative address instructions have the same instruction
range.
* The instruction range is -4,095 to +4,095 bytes from the current adjusted PC.
The PC is aligned down to a four-byte boundary before the offset is added.
* Automatically-placed literals (ie. those created by `Literal<T> x(value)`)
will be emitted into code such that they are in range of the instructions that
refer to them.
* Veneers are not applied to manually-placed literals, ie. those created by
`Literal<T> x(value, RawLiteral::kManuallyPlaced)` and emitted by `Place()`.