General Apple Silicon/ARM64 Assembly Notes

[CuriousTommy]

Since I'm not familiar with ARM64 assembly, I figured I would make a public diary about my experiences learning about it. Hopefully this can be helpful for others who are learning/struggling.

Useful Resources

• https://github.com/below/HelloSilicon

[CuriousTommy]

Linux/General ARM64 Assembly Notes

Machine Registers

General-purpose Registers

Register	Special	Role in the procedure call standard
SP		The Stack Pointer.
r30	LR	The Link Register.
r29	FP	The Frame Pointer
r19…r28		Callee-saved registers
r18		The Platform Register, if needed; otherwise a temporary register. See notes.
r17	IP1	The second intra-procedure-call temporary register (can be used by call veneers and PLT code); at other times may be used as a temporary register.
r16	IP0	The first intra-procedure-call scratch register (can be used by call veneers and PLT code); at other times may be used as a temporary register.
r9…r15		Temporary registers
r8		Indirect result location register
r0…r7		Parameter/result registers

Frame Pointer

TODO:

While this message is about x86_64 assembly, it gives a good explanation on what a frame pointer is.

Source: https://discord.com/channels/587344761107513532/858049574090702888/1126012876977610812

To add to what @\facekapow says, perhaps to answer the more fundamental question: the frame pointer points at the start of the current function's frame, while the stack pointer points to the end of the frame. So the two pointers together delimit the current frame.

Why is there a need for the frame pointer? — technically you can do without it, but some things are easier/nicer with it:

• referencing on-stack function arguments and local variables is more convenient to do relative to the frame pointer, otherwise (to do it relative to the stack pointer) you need to track how big your frame is (=how far the stack pointer is from the frame pointer), and this is especially tricky with VLAs and alloca
• exiting from the function is easy, you can just leave; ret (where leave is the same as mov %rbp, %rsp; pop %rbp), otherwise you'd have to add the appropriate offset to the stack pointer, which again you'd need to track
• unwinding/backtracing is easier, since you can pretty much just follow a chain of saved frame pointers all pointing to each other and delimiting frames

Link Register

Source: https://en.wikipedia.org/wiki/Link_register

A link register (LR for short) is a register which holds the address to return to when a subroutine call completes. This is more efficient than the more traditional scheme of storing return addresses on a call stack, sometimes called a machine stack. The link register does not require the writes and reads of the memory containing the stack which can save a considerable percentage of execution time with repeated calls of small subroutines.

SIMD and Floating-Point registers (NEON)

AArch64 has 32 x 128-bit NEON registers (V0-V31). These registers can also be viewed as 32-bit Sn registers or 64-bit Dn registers.

Register Alignment

127	95	63	31	0
			s0
		d0	--
v0	--	--	--

Register	Role in the procedure call standard	Notes
v0-v7	pass argument values into a subroutine and to return result values from a function
v8-v15	Callee-saved registers	All other registers do not need to be preserved by the callee
v16-v31	Temporary registers

Condition Flag

Flag	Name	Description
N	Negative	Set to the same value as bit[31] of the result. For a 32-bit signed integer, bit[31] being set indicates that the value is negative.
Z	Zero	Set to 1 if the result is zero, otherwise it is set to 0.
C	Carry	Set to the carry-out value from result, or to the value of the last bit shifted out from a shift operation.
V	Overflow	Set to 1 if signed overflow or underflow occurred, otherwise it is set to 0.

Condition Codes

Code	Encoding	Meaning (when set by CMP)	Meaning (when set by FCMP)	Condition flags
EQ	0b0000	Equal to.	Equal to.	Z =1
NE	0b0001	Not equal to.	Unordered, or not equal to.	Z = 0
CS	0b0010	Carry set (identical to HS).	Greater than, equal to, or unordered (identical to HS).	C = 1
HS	0b0010	Greater than, equal to (unsigned) (identical to CS).	Greater than, equal to, or unordered (identical to CS).	C = 1
CC	0b0011	Carry clear (identical to LO).	Less than (identical to LO).	C = 0
LO	0b0011	Unsigned less than (identical to CC).	Less than (identical to CC).	C = 0
MI	0b0100	Minus, Negative.	Less than.	N = 1
PL	0b0101	Positive or zero.	Greater than, equal to, or unordered.	N = 0
VS	0b0110	Signed overflow.	Unordered. (At least one argument was NaN).	V = 1
VC	0b0111	No signed overflow.	Not unordered. (No argument was NaN).	V = 0
HI	0b1000	Greater than (unsigned).	Greater than or unordered.	(C = 1) && (Z = 0)
LS	0b1001	Less than or equal to (unsigned).	Less than or equal to.	(C = 0) || (Z = 1)
GE	0b1010	Greater than or equal to (signed).	Greater than or equal to.	N==V
LT	0b1011	Less than (signed).	Less than or unordered.	N!=V
GT	0b1100	Greater than (signed).	Greater than.	(Z==0) && (N==V)
LE	0b1101	Less than or equal to (signed).	Less than, equal to or unordered.	(Z==1) || (N!=V)
AL	0b1110	Always executed.	Default. Always executed.	Any
NV	0b1111	Always executed.	Always executed.	Any

Exception Levels

EL0	EL1	EL2	EL3
Application	Rich OS	Hypervisor	Firmware / Secure Monitor
<--	<--	<--	<-- Decreasing privilege
Increasing privilege -->	-->	-->	-->

Loads and Stores Addressing

• Base register

; x1 stays the same
; w0 = x1[0]
ldr w0, [x1]

flowchart TD
    A[x1] -->|Memory| B(w0)

Loading

• Offset addressing modes

; x1 stays the same
; w0 = x1[12]
ldr w0, [x1, #12]

flowchart TD
    A[+] -->|Memory| B
    B[w0]
    C[x1] --> A
    D[#12] --> A

Loading

• Pre-index addressing modes

; x1 updated to x1 + 12
; w0 = x1[12]
ldr w0, [x1, #12]!

flowchart TD
    A[+] --->|Memory| B
    A --> E
    B[w0]
    C[x1] --> A
    D[#12] --> A
    E["x1 (updated)"]

Loading

• Post-index addressing modes

; x1 updated to x1 + 12
; w0 = x1[0]
ldr w0, [x1], #12

flowchart TD
    A[x1] ---->|Memory| B
    A --> D
    B[w0]
    C[#12] --> D
    D[+] --> E
    E["x1 (updated)"]

Loading

Calling Convention

; Preserve the frame pointer and link register
;     Keep in mind that instructions (like `bl`), can overwrite the link register. So it's
;     important to preserve this register. Otherwise, you may run into an infinite loop...
stp fp, lr, [sp, #-16]!
; Move the stack pointer (`sp`) to the frame pointer register
mov fp, sp

; TODO: Add examples for setting functions arguments.
; TODO: Add examples for return arguments.

; Restore the frame pointer and link register
ldp fp, lr, [sp], #16
ret

Source

• Procedure Call Standard for the Arm® 64-bit Architecture (AArch64)
  • General Purpose Registers
  • A64 -- Base Instructions
• ARM Cortex-A Series Programmer's Guide for ARMv8-A
  • Conditional instructions
• AArch64 Exception Levels
• Learn the architecture - AArch64 Exception Model
  • Exception levels
• Learn the architecture - A64 Instruction Set Architecture
  • Loads and stores - addressing
• Arm NEON programming quick reference
• ARM64 Calling Convention Cheat Sheet

[CuriousTommy]

MacOS ARM64 Assembly Notes

Syscall

Unlike Linux, macOS discourages the usage syscalls. This means that applications that rely on syscalls may break in the future, as macOS makes no promises for stability.

OS	Instruction	System Call Number	System Return Value 1	System Return Value 2
Linux	svc #0	w8	x0	x1
macOS	svc 0x80 [1]	x16	x0	x1

[1] The intermediate value does not seem to matter. With that being said, Apple's own software seems to have it set to 0x80.

OS	arg1	arg2	arg3	arg4	arg5	arg6	arg7	arg8	arg9
Linux	x0	x1	x2	x3	x4	x5	---	n/a	n/a
macOS	x0	x1	x2	x3	x4	x5	x6	x7	x8

High level notes on handle_svc (based on xnu-7195.141.2)

IF trap_no EQUALS 0x80000000 (PLATFORM_SYSCALL_TRAP_NO)
    RUN platform_syscall
    PANIC (platform_syscall is noreturn)

IF trap_no LESS THAN 0
    IF  trap_no EQUALS -3 (MACH_ARM_TRAP_ABSTIME)
        RUN handle_mach_absolute_time_trap
    ELSE IF trap_no EQUALS -4 (MACH_ARM_TRAP_CONTTIME)
        RUN handle_mach_continuous_time_trap
    ELSE
        RUN mach_syscall
ELSE
    RUN unix_syscall

High level notes on ‎platform_syscall (based on xnu-7195.141.2)

// There is some additional stuff that Apple does in there code, but to keep things simple, we will ignore that
// Apple code actually uses TPIDRRO_EL0, but unless Linux provides a way for us to update that value from user space, we will have to use TPIDR_EL0 instead...
// Case 0 and 1 used to handle the cache flush, but now it does nothing.

ASSIGN r3 TO code

IF code IS 2:
    // RUN set_tpidrro(r0)
    ASM("msr TPIDR_EL0, r0")

ELSE IF code IS 3:
    // RUN get_tpidrro()
    ASM("mrs r0, TPIDR_EL0")

Syscall Implementation For Darling

Macros for how to handle more than one return argument/error flag:

#define ARM64_SET_SECOND_RETURN_VALUE(value) \
asm volatile (                \
    "mov x1, %[return2]\n" :: \
    [return2] "r"(value)      \
)

// Apple treats the carry flag as the error flag
#define ARM64_SET_ERROR_FLAG \
asm volatile (                  \
    "mrs x9, nzcv\n"            \
    "orr x9, x9, 0x20000000\n"  \
    "msr nzcv, x9"              \
)

#define ARM64_CLEAR_ERROR_FLAG \
asm volatile (                  \
    "mrs x9, nzcv\n"            \
    "mov x10, 0x20000000\n"     \
    "bic x9, x9, x10\n"         \
    "msr nzcv, x9"              \
)

Variadic Functions

TODO

Address Space Size

TODO

https://discord.com/channels/587344761107513532/858049574090702888/1244323294229041164
https://discord.com/channels/587344761107513532/858049574090702888/1244326180069441548

Sources

• handle_svc Function - xnu-7195.141.2
• iOS ARM64 Syscalls - Stack Overflow
• Writing ARM64 code for Apple platforms
• ARM Compiler armasm User Guide Version 6.00 - Updates to the condition flags in A64 code
  • NZCV, Condition Flags
• Addressing Architectural Differences in Your macOS Code
  • Enable Strict Type Enforcement for Dynamic Method Dispatching

[CuriousTommy]

CFI (Call Frame Information)

Not directly related to ARM64 assembly, but useful to know when dealing with debugging/exception handling.

TODO: Add more notes about CFI

Sources

• CFI directives in assembly files
  • Note: This blog post uses x86_64 assembly.