ARM64 → x86_64
How Digitalis Works

00 What we'll cover

Ten parts, one journey

Written for readers new to CPUs and assembly — Part 0 starts from nothing. Amber = ARM64 (guest); steel = x86_64 (host) — used consistently throughout.

0 Foundations · What a program becomes

The code you write is not the code that runs

You write text. A compiler turns that text into machine code — numbers a specific processor recognises as commands. By the time an app ships, the readable part is gone.

Those eight bytes are the product. The app store ships bytes like these; no phone ever sees your source code — and the mnemonics above are a convenience for readers, not something the chip stores.

0 Foundations · What a processor does

A CPU is a very fast, very literal loop

A processor has no idea what an app is. It repeats three steps, billions of times a second, and never looks further ahead than the next command.

Everything in this deck is a consequence of step 2: the bits only mean something to a chip that was built to read them that way.

0 Foundations · Registers

Registers: the desk the CPU works on

A processor cannot do arithmetic on memory the way you might imagine. It works on a tiny set of named slots built into the silicon — registers — each holding one number.

Remember the desk metaphor: how many sheets each architecture gives you is the single biggest headache in this whole project.

0 Foundations · Instruction sets

An instruction set is a vocabulary — and chips speak different ones

The list of commands a processor understands, and the exact bit patterns that mean each one, is its instruction set architecture — its ISA. Two ISAs matter here.

Neither is "better" here. They are simply different languages — and a program is written in exactly one of them.

0 Foundations · The same idea, twice

One task, two spellings

"Add the numbers in two slots and put the answer in a third." Both chips can do it. Neither can read the other's version of it.

Same intent, different grammar — and one ARM64 instruction already needed two x86_64 ones. Hold on to that; it is the shape of the whole problem.

0 Foundations · Flags

How a CPU remembers the last comparison

Programs branch: if this is bigger, then do that. A processor splits that into two steps, and keeps a scrap of memory between them called the flags.

Both architectures have flags. They do not agree on what the bits mean — subtraction sets the carry bit oppositely. That mismatch gets a slide of its own later.

0 Foundations · What an app ships

Which part of an app is tied to a chip?

Most Android code is not machine code. It ships as portable bytecode that the phone finishes compiling on arrival — so it runs anywhere. The exception is the part written in C or C++.

An app declares which chips its native code supports by which folders it packs — lib/arm64-v8a/, lib/x86_64/. That naming is called an ABI.

0 Foundations · The mismatch

Phones are ARM. Development machines are not.

The Android emulator is not a simulation of a phone's processor — it runs at full speed precisely because it uses the real CPU of the machine it is on. Which is almost never an ARM chip.

So an ARM64-only app meets an x86_64 emulator and simply stops. Making that meeting work is the entire project.

0 Foundations · The options

Three ways to run code built for another chip

Only one of them is available to somebody who has an APK and no source code.

Option 3 is what Digitalis does. The rest of the deck is how.

0 Foundations · Interpret vs. translate

The interpreter and the translator

Two ways to handle a foreign language, and the same trade-off a human would face.

Real systems use both: translate what runs often, interpret the rare and awkward. Digitalis has three such gears — Part IV.

0 Foundations · At runtime

"At runtime" means there is no build step

Nothing is converted ahead of time. The app is installed exactly as its author shipped it, and translation happens in the fraction of a second before each piece of code first runs — then never again for that piece.

This is why the app cannot tell. There is no patched APK, no repackaging, no second copy — the original bytes are what got installed.

0 Foundations · Where the hard part hides

Translating the instructions is the easy half

If a program only did arithmetic, this deck would be short. Real code constantly asks the world around it for things — and that world is now the wrong shape.

Parts V through VII are almost entirely about these three, not about instructions.

0 Foundations · Asking the operating system

System calls: the one door out of a program

A program cannot touch a file, a screen or a network by itself. It must ask the operating system, through a system call — and the asking is itself a machine instruction.

Different instruction, different numbering, sometimes differently-shaped arguments. Every one of these has to be caught and rewritten — Part VII.

0 Foundations · Vocabulary

Ten words the rest of the deck assumes

• guest
  the ARM64 world being emulated — the app's code, registers and memory
• host
  the real x86_64 machine and its operating system, doing the actual work
• register
  one numbered slot inside the CPU holding a single value
• PC
  program counter — the register holding the address of the next instruction
• ISA
  instruction set architecture: the vocabulary of one chip family, e.g. ARM64
• ABI
  the naming and calling conventions binaries must agree on, e.g. arm64-v8a
• JIT
  just-in-time: generating machine code while the program runs, not before
• region
  a straight run of guest instructions translated together as one unit
• syscall
  a program's request to the operating system to do something for it
• SIMD
  one instruction operating on several numbers at once — NEON on ARM64, SSE on x86_64

0 Foundations · How to read this deck

Three depths — take the one you want

The colours are used consistently from here on: if something is amber it belongs to the app's world, if it is steel it belongs to the machine.

I The Problem

An ARM64 app, an x86_64 machine, a wall between them

Android emulators — on laptops, cloud CI, and dev machines — run on x86_64. Many apps are built only for ARM64. Those two facts collide.

Digitalis makes that app run anyway — by translating its ARM64 code to x86_64 at runtime. The app doesn't know the difference.

I The Problem · Anatomy of an app

Two kinds of code live inside every app

A well-behaved app ships both folders. The problem apps ship only arm64-v8a/ — and then there is simply no native code an x86_64 CPU can execute.

I The Problem · What failure looks like

Two ways the wall shows itself

e_machine: 183 is 0xB7 — the ELF header's code for AArch64. The loader is saying: "this file is for a CPU I am not."

I The Core Idea

Binary translation: a live interpreter for CPUs

ARM64 and x86_64 are two languages processors speak. Both can add, load, branch, and call — they just spell every operation differently. A binary translator reads one and produces the equivalent in the other, on the fly.

Like a simultaneous interpreter at a conference — not for spoken languages, but for CPU instruction sets.

I The Vocabulary That Runs Through Everything

Guest and Host

• register
  a tiny, ultra-fast storage slot built into the CPU that holds one number
• PC
  the program counter — the register holding the address of the instruction about to run
• syscall
  how a program asks the OS kernel for things it can't do itself (files, network, time)
• ABI
  the contract for how arguments and return values are passed between functions

Like a guest staying in someone's home. These words appear in nearly every part of the system — keep them straight and the rest follows.

II History · Part 1

Where "ARM on x86" began

• ~2012
  Intel Atom Android phones arrive. Devices like the Motorola RAZR i ran Android on x86 processors. Java apps were fine — but thousands of apps carried ARM-only native libraries an x86 CPU couldn't run. Intel had a store-compatibility crisis.
• Houdini
  Intel's answer: a proprietary translator. Intel shipped libhoudini, a closed-source ARM→x86 binary translator. Slip it under an ARM library and the calls quietly became x86. The first widely-used ARM-on-x86 layer for Android.
• android-x86
  The community needed it too. The android-x86 project ported Android to ordinary PCs and laptops. For ARM-only apps it leaned on Houdini-style translation — the same trick, now on desktop hardware, but still dependent on a binary blob nobody could read or fix.

Houdini worked — but it was closed-source and vendor-controlled. You couldn't read it, fix it, or extend it. That constraint shaped everything that came next.

II History · Part 2

2014: Android grows a standard socket

With Android 5.0, Google built NativeBridge into the runtime (ART): a pluggable interface that any binary translator can attach to. AOSP defines the socket; a vendor supplies the translator behind it.

The turning point: "run foreign CPU code" becomes a defined extension point in Android, not a per-device hack.

II History · The socket matured

NativeBridge grew for a decade — eight versions

The interface started minimal and absorbed a decade of hard lessons. Each version records a real problem someone hit:

We'll meet the actual callbacks — initialize, loadLibraryExt, getTrampoline…, getSignalHandler — in Part V.

II History · Part 3

Berberis opens the box — Digitalis widens it

• Berberis
  Google's open-source translator in AOSP. Unlike Houdini, you can read and modify every line. It was built first for RISC-V → x86_64 and plugs into NativeBridge like any other bridge.
• Digitalis
  The ARM64 backend for Berberis. Berberis had the engine — cache, dispatch, assembler, proxy machinery — but no ARM64 support. Digitalis adds the entire ARM64 → x86_64 half: decoder, JIT, interpreter, syscall layer, proxies.

Same job Houdini once did — opposite philosophy: open, inspectable, extensible.

II The Lineage at a Glance

From vendor black box to open backend

Amber nodes are ARM-focused milestones; steel nodes are the open AOSP framework and its backends.

II The Cousins

The same idea, elsewhere in the industry

Binary translation quietly powers several famous migrations. Digitalis sits in a well-established family:

Note the directions: Rosetta and Windows translate toward ARM (new hardware, old apps); Android emulation translates away from ARM (ARM apps, x86 hardware). Same machinery, mirrored motive.

III Two Worlds · Overview

Tidy vs. dense

Underneath every app, a CPU runs a stream of simple operations: arithmetic, loads and stores, comparisons, branches, system calls. Both architectures do all of them — with opposite temperaments.

Same capabilities, opposite temperaments — each row is one difference the translator must reconcile; the rest of this part walks through them.

III Two Worlds · Registers

Registers: the CPU's scratch paper

Registers are labeled boxes inside the CPU, each holding one number. Reading one takes under a nanosecond; reaching main memory takes ~100× longer. Every arithmetic operation works on registers.

Each register also has narrower views of itself — and the two architectures disagree on a subtle rule about them:

The translator must reproduce ARM64's zero-extension rule exactly — get it wrong and later 64-bit math sees leftover garbage in the top half.

III Two Worlds · The register mismatch

31 boxes on one side, 16 on the other

The count mismatch — 31 vs 16 — is one of the biggest challenges in translation, and drives the register allocator we'll meet in Part VI.

III Two Worlds · Condition flags

The four bits branches depend on

After arithmetic, a CPU sets condition flags as a side effect — was the result zero? negative? did it overflow? A following conditional branch tests them. Both sides have flags; they disagree on layout and one crucial meaning.

ARM64's Carry after subtract is the inverse of x86_64's borrow. Every translated compare must flip that bit, or "branch if carry" takes the wrong path — Part VI shows the exact fix.

III Two Worlds · Instruction encoding

Fixed width vs. variable width

Good news for the translator: the input (ARM64) is the easy one to read, and the tricky output (x86_64) only has to be generated — never decoded. One dedicated assembler component handles all the x86_64 encoding complexity.

Two lucky breaks worth naming: both architectures are little-endian (bytes stored least-significant first), so data needs no conversion — and one ARM64 instruction becomes only 1–5 x86_64 instructions, not dozens.

III Two Worlds · One instruction, bit by bit

Anatomy of ADD X1, X2, X3

This one instruction — "X1 = X2 + X3" — is encoded as the 32-bit word 0x8B030041. Every field lives at a fixed bit position:

• no opcode field
  There's no single "this is ADD" number — the operation is spread across sf, op, S, and the class bits. Decoders read fields, not opcodes.
• bits [28:25]
  The decoder's first question: these four bits route every ARM64 instruction into one of five big families (Part VI).
• little-endian
  In the file, 0x8B030041 is stored as the bytes 41 00 03 8B — least significant first.

III Two Worlds · The same add, translated

"Add two numbers," both ways

Small detail, huge cumulative effect: this three-operand vs two-operand mismatch is why translated code sprouts extra movs throughout.

III Two Worlds · The phrasebook

Same intent, different spelling — a mini dictionary

III Two Worlds · The vector units

One instruction, four numbers at once

Both CPUs can apply the same arithmetic to several values in a single instruction — SIMD, "Single Instruction, Multiple Data". Graphics, audio, video and machine-learning code is built almost entirely out of it.

A vector register is one wide slot holding several numbers packed end to end. ARM64 calls its vector unit NEON; x86_64 calls its equivalent SSE.

This is where the performance of a game or a video codec actually lives — which is why a translator that handled only ordinary arithmetic would be useless in practice.

III Two Worlds · A lucky match, an awkward mismatch

The widths line up. The counts do not.

Next slide: what that fetching actually costs.

III Two Worlds · Borrowing a vector register

What "no permanent home" costs

A guest vector operation becomes a small ritual: load the two operands out of the guest CPU record into scratch host registers, do the one real instruction, store the answer back.

• why it is fine
  Simple, and always correct. The loads hit the innermost cache, so the cost is real but small — and Part VI's optimiser removes the redundant ones inside hot loops.
• rbp
  A host register permanently pointing at the guest CPU record, so any guest register is one memory access away. Part VI explains the arrangement.
• AVX unused
  Wider 256- and 512-bit host vectors exist, but 128-bit NEON semantics gain nothing from them — Digitalis deliberately stays on plain SSE.

III The guest's vocabulary · the shape of it

Six things any program ever needs to say

A table of a dozen instruction families is coming. It is much easier to read once you notice that every one of them serves one of six intentions — and that this list would be the same for any processor ever built.

The translator must handle all six, and it handles them very differently — the fourth and sixth are where nearly all the difficulty lives.

III The guest's vocabulary · in full

ARM64's instruction families

The same six intentions, now as the architecture actually groups them — with the path each family takes through Digitalis. Skim this; do not memorise it. The one column that matters is the last.

The pattern to notice: ~98% of what real apps execute lands in the JIT rows; the interpreted rows are rare by construction.

III The host's toolbox · the strategy

The translator writes only boring instructions

Reading and writing are not symmetrical. Digitalis must understand every ARM64 instruction an app might contain — but it gets to choose which x86_64 instructions it emits, and it chooses conservatively.

"Use the oldest instruction that does the job" sounds unambitious. It is what makes translated code run identically on a 2010 laptop and a 2025 server.

III The host's toolbox · in full

x86_64's instruction families

The same strategy as a table — every family the host offers, and what Digitalis does with it. Again: skim.

A deliberate asymmetry: Digitalis must read every ARM64 family but only writes the host families it chooses — so it leans on the boring, universally-available ones and treats everything past SSE2 as optional acceleration.

III SIMD · lanes

One register, many lanes

A SIMD register is a 128-bit box that both architectures slice into lanes — and one instruction operates on every lane at once. ARM64 writes the slicing right into the operand name:

That JIT/interpreter split is the practical rule of thumb: lane-parallel = fast path, lane-crossing = fallback. This is where most of the "~2% interpreted" instructions come from.

IV Strategy 1

The interpreter: simple, universal, slow

The simplest way to run foreign code is a loop that mimics each instruction, one at a time, against a software copy of the guest CPU.

It handles any instruction — but every guest instruction costs many host instructions of overhead. Typical slowdown: 10–50×.

Like cooking from a foreign-language recipe by translating each line in your head as you go. Correct, works for any recipe — but slow.

IV Strategy 2

The JIT: translate once, run native

A Just-In-Time compiler doesn't mimic instructions — it generates real x86_64 machine code and runs that directly on the host CPU.

Like translating the whole recipe onto a card once, then cooking straight from the card every time after. Digitalis's JIT is called the Lite Translator.

IV The unit of work

Regions: straight-line runs of code

The JIT doesn't translate one instruction at a time — it takes a region: a run of instructions with no branch into the middle, compiled into one block of x86_64 and cached as a unit.

• ends on
  Unconditional branch or call — the target may not be translated yet. (Conditional forward branches don't end it: the JIT emits a taken-path exit and keeps compiling.)
• ends on
  Backward branch — loop edge; ending here guarantees pending signals get checked between iterations.
• ends on
  Register pressure — the allocator is running low on host registers.
• survives
  Partial success — if instruction 8 of 12 can't be compiled, the JIT still installs the working prefix (1–7); the straggler routes to the interpreter.

IV The heartbeat

The translation cache & dispatch loop

The cache maps each guest address to a host code pointer. The dispatch loop — ExecuteGuest() — runs forever: read the guest PC, look it up, jump to whatever's there.

It's an indirect jump, not a giant switch — the cache stores raw code pointers, and the loop's only explicit check is "should I stop?" Everything else routes through the pointer itself.

IV An address's life

How a guest address moves through the cache

Digitalis translates every region on first encounter — the translation threshold is zero. The bet: JIT cost is always low enough to pay off, so skip the usual "is this hot yet?" profiling for the first pass.

While an address has no real code, the cache stores a signpost instead: "not translated — compile me", "route to interpreter", "another thread is compiling — retry", or "stop, thread exiting."

IV Three gears

The cheapest path that works, then promote

Safety net: any tier that meets an instruction it can't handle drops to a slower tier that can — correctness never depends on the fast path.

IV Gearing up · a worked scenario

How a hot loop earns the second gear

Every lite region carries an invocation counter. Take a 34-instruction loop body inside a real app:

• ≥ 20 insns
  The size gate: a 12-instruction micro-loop stays lite forever — recompiling it would cost more than it could ever save. Tiny loops are never regressed.
• what heavy does
  Lowers the whole region into an SSA intermediate form ("every value written exactly once"), then does global register allocation, hoists loop-invariant work, and eliminates redundant guest-state loads/stores — things a one-pass translator can't see.
• safe bail
  If heavy meets an instruction it doesn't support, the region simply settles back at lite — a missed optimization, never a crash.

IV The map so far

One decoder, three consumers

All three tiers share the same front door: the decoder reads ARM64 bits; a thin bridge (the "semantics player") hands each decoded instruction to whichever tier is running.

This shape has a project rule attached: when a common instruction is added or fixed, it must be covered in every tier where it's reachable — a gap in one tier degrades that tier silently.

V NativeBridge

Android's plug for translators

NativeBridge is a plugin system inside Android's runtime (ART). When it meets an app whose native libraries are the "wrong" architecture, it loads the bridge library and hands it the hard parts.

The same socket Houdini once filled — Digitalis is simply a different implementation behind it. Even installs work: if an APK has no matching ABI but a bridge is present, the package manager selects a bridge-compatible ABI instead of rejecting it.

V NativeBridge · Lifecycle

Four states from cold to ready

The odd-looking middle step matters: pre-initialization runs with elevated privileges — after Android's template process (Zygote) forks the app but before it drops to the app's restricted permissions — so the bridge can create its code-cache directory while it still can.

V NativeBridge · The interface

One symbol, a table of callbacks

Everything ART asks of the bridge goes through the NativeBridgeItf function table. The important entries, and what Digitalis does behind each:

Sequence at boot: init starts Zygote → Zygote loads the bridge (property → dlopen → dlsym) → every app process forked from Zygote inherits it, already opened.

V Startup · Building the guest world

An ARM64 environment inside an x86_64 process

The host kernel refuses to load an ARM64 binary — wrong architecture. So Digitalis loads it itself, doing in user space what the kernel normally does. Its minimal ELF loader, TinyLoader, bootstraps exactly three files:

• division of labor
  TinyLoader only maps ELF segments into memory and zeroes .bss — it deliberately skips relocations (the address patches a library needs once its load address is known). That's the guest linker's job, and TinyLoader loads that linker first.
• the trick
  linker64 then runs under translation and loads libc and everything else via normal dynamic linking — it doesn't know it's being translated. Digitalis drives it through its exported __loader_* functions (dlopen, dlsym, create_namespace).
• the swap
  When the linker asks for a system library, the namespace search path leads to /system/lib64/arm64/ — where proxy libraries stand in for the host's real ones (Part VII).

V Startup · The address space

One process, two worlds — a map

There is no separate "guest memory." Everything shares one x86_64 process address space (addresses illustrative — randomized every launch):

Amber regions hold ARM64 bytes (data to the host CPU); steel regions hold x86_64 the CPU actually executes. When TinyLoader maps an ARM64 segment it gets a real host address, and the guest runs "at" that address — no address translation, ever.

V Startup · Rules of the shared space

Three consequences of one address space

V Startup · Crossing from Java

Trampolines: the Java → ARM64 doorway

When Java calls a native method, ART knows the x86_64 calling convention — but the target function is ARM64. The bridge generates a trampoline: a small x86_64 wrapper that catches the call, converts it, and enters the guest.

One pointer needs special care: JNIEnv* is itself a table of function pointers — a guest env holds guest-callable pointers, so it can't cross to host code unchanged. JNI trampolines translate it both ways.

V Startup · The fast-call page

vDSO: the syscall that isn't

The kernel maps a tiny library — the vDSO — into every process, so hot calls like gettimeofday() skip the kernel entirely:

• problem
  The host kernel maps an x86_64 vDSO — guest ARM64 code can't call it. But the guest linker expects an ARM64 vDSO; without one it may load a rogue copy with no translator hooks.
• solution
  TinyLoader pre-loads a Berberis-provided ARM64 vDSO and hands its address to the guest linker through the auxiliary vector (AT_SYSINFO_EHDR) — exactly the way the kernel would.
• bonus
  The syscall layer answers clock_gettime / gettimeofday inline without entering the kernel — keeping the guest's cheap calls cheap under translation too.

VI The three data structures

What the whole system passes around

Even a debugger obeys this contract: on a crash, Android's debuggerd reads the guest registers out of ThreadState (tagged with the magic string "BERBERIS") and prints an ARM64-shaped crash dump.

VI Register allocation

Fitting 31 guest registers into 13 host slots

Three host registers are reserved (RAX, RBP, RSP — previous slide). The remaining 13 form the mapping pool, handed out in a deliberate order:

• first touch wins
  The first 13 distinct guest registers a region touches get permanent host slots for the whole region.
• the 14th register
  Doesn't end the region — it's spilled: each use borrows a scratch register, loads the value from ThreadState memory, and stores it back. Slower, always correct.
• desk analogy
  A desk with room for 13 sheets of paper: need a 14th, file one back in the drawer (memory), work on the new sheet, pull the filed one out when needed again.

Spilling first — rather than cutting the region — keeps translated blocks long, and long blocks are what make the JIT fast.

VI Reference · the complete mapping

ARM64 → x86_64: where everything lives

Three host registers are reserved outright (RAX, RBP, RSP), thirteen are pooled for guest integers, XMMs are borrowed per vector operation — and every guest register that misses out is answered from ThreadState memory.

VI Reference · crossing the boundary

And when a call leaves the guest world

The mapping above covers guest code talking to itself. The moment translated code calls a real host function — the C library, the graphics driver — a second mapping applies: the calling convention, which says where a function looks for its arguments.

• 8 into 6
  ARM64 passes up to eight arguments in registers; x86_64 only six. Arguments seven and eight have to be moved onto the stack — a real conversion, not a rename.
• the return address
  ARM64 keeps it in a register (X30); x86_64 pushes it onto the stack. Every call and every return has to translate between the two habits.
• the syscall trap
  Both use a register for the syscall number — but the numbers themselves differ. "Write" is 64 on ARM64 Linux and 1 on x86_64. Part VII is largely about that table.

VI Register allocation · worked example

A summation loop needs no spill at all

Four guest registers, four host slots, 9 of 13 left unused — the common case. Every iteration runs entirely out of host registers; ThreadState is touched only at region entry and exit.

The practical moral: values kept in the first few registers a function touches win the permanent slots — late arrivals pay the memory round-trip. Compiler-generated code naturally behaves this way.

VI Decoding

Figuring out what an instruction is

Before anything can be translated, the decoder reads the 32 bits and extracts operation and operands. Its first question — bits [28:25] — splits every ARM64 instruction into five families:

VI One instruction, whole pipeline

Following STR X1, [X0, #16] all the way through

A store from the app's real init code — state->device = device; in C — traced through every stage:

• 1 · decode
  Read 4 bytes at the PC. Bits[28:25] = x1x0 → loads/stores family → STR with immediate offset. Fields: source X1, base X0, offset 16, size 64-bit.
• 2 · bridge
  The semantics player calls the JIT's Store() with those decoded fields.
• 3 · allocate
  X0 is already mapped to RSI, X1 to RDI (earlier instructions touched them).
• 4 · emit
  The assembler produces mov [rsi+16], rdi — bytes 48 89 7E 10 — plus a paired recovery stub in case the address faults.
• 5 · install
  The finished region (this store and its neighbors) lands in the TranslationCache under its guest address.
• 6 · forever after
  Every future visit runs the cached bytes directly. No decoding, no allocation, no emission — just mov [rsi+16], rdi.

This is the entire business model of the JIT in one instruction: pay the pipeline once, keep the four bytes of output forever.

VI Making bytes

The assembler: an x86_64 encoder as an API

The JIT never writes hex by hand. It calls methods on an assembler object, which knows every x86_64 encoding rule — prefixes, register codes, immediate sizes:

• backpatching
  A forward jump's target doesn't exist yet — so the assembler emits a placeholder offset, records the spot, and overwrites it once the target label is bound. Like writing "see page ___" in a draft and filling in the blank when the final page number is known.
• direct wins
  Some ARM64 instructions map beautifully: byte-reverse REV → one BSWAP; count-leading-zeros CLZ → BSR + XOR 63. The translator takes every gift the host offers.

VI Making bytes runnable

W^X and the dual-mapped code cache

Modern systems enforce W^X: a memory page may be writable or executable, never both — it blocks the classic write-then-run attack, but equally blocks a well-behaved JIT. Digitalis threads the needle with one block of memory mapped twice:

Neither view ever violates W^X — no page is writable and executable — yet freshly generated code is runnable immediately. A pre-allocated code pool parcels out these regions, avoiding a system call per translation.

VI Reconciling the flags · worked trace

Packing x86_64 flags into NZCV — with real values

Every flag-setting guest instruction ends with a fixed little epilogue. Here it is for SUBS X0, X5, X6 computing 10 − 10:

Seven host instructions, of which one does the arithmetic and six exist purely so the guest's four flag bits end up correct. Read the next slide for why the sixth is the interesting one.

VI Reconciling the flags · the disagreement

The two architectures disagree about subtraction

Flags are the one place where the same event produces the opposite answer on each side — so copying the bits across would be silently, catastrophically wrong.

This is the deck's recurring theme in miniature: the instructions are the easy part, and the conventions around them are where correctness is won or lost.

VI Reconciling the flags · two traps

Two details that bite

• why LAHF
  It grabs Sign/Zero/Carry in one instruction. A subtlety hides here: stack-pointer adjustments before LAHF must use PUSH/POP or LEA — an innocent-looking sub rsp, 8 would destroy the very flags being captured.
• bit layout
  The packed word puts N at bit 15, Z at 14, C at 8, V at 0 — hence the 0xC101 mask, and the final 0x4100 = "Zero set, Carry set."

Both are the kind of detail that only shows up as a mysterious wrong answer thousands of instructions later.

VI When code faults · worked example

A crash must belong to the guest

Suppose guest code runs LDR X1, [X0] with X0 = 0xDEAD — an unmapped address. The fault happens in translated code, so the host kernel raises a host SIGSEGV. But many apps install their own crash handlers; the signal must reach them, shaped like ARM64.

• 1
  The translated mov rcx, [rsi] faults; the host kernel delivers SIGSEGV to Digitalis's handler.
• 2
  The handler looks the faulting host address up in a recovery map — every JIT load/store was emitted with a paired recovery stub.
• 3
  The stub knows the guest PC of the original LDR: it writes that PC into ThreadState, queues the signal, and exits generated code cleanly.
• 4
  The dispatch loop sees the pending signal and calls the guest's registered handler as translated ARM64 code — with an ARM64-layout context and si_addr = 0xDEAD.
• 5
  Handler returns → execution resumes wherever the (possibly modified) guest PC points. No handler → a tombstone is written showing the guest registers, X0 = 0xDEAD included.

The interpreter needs the same care: its memory accesses go through special faulting load/store stubs — a raw memcpy would crash the host process with no route back to the guest's handler.

VI The cache must stay honest

Apps that rewrite their own code

JavaScript engines, ART itself, regex engines — many apps contain their own JITs, generating fresh ARM64 at runtime. That collides with a translator's central assumption: that translated code stays valid.

Treating IC IVAU as a harmless no-op — tempting, since x86 needs no such flush — means silently running stale translations of deleted code. A real Qt app crashed exactly this way (its regex engine regenerates code) until the invalidation was wired up.

VII Proxy libraries

An adapter on the boundary

Every system library the app calls — Vulkan, libc, audio — exists on the device as native x86_64. Translating those would be wasted work. Instead, a proxy library stands in for each one and reshapes the call:

Like a travel plug adapter: the electricity (your data) is the same on both sides — only the shape of the plug (which register holds each argument) differs between countries. The full set: libc, libm, libvulkan, libEGL, libGLESv1_CM/v2/v3, libaaudio, libOpenSLES, libOpenMAXAL, libamidi, libcamera2ndk, libmediandk, libandroid, libandroid_runtime, libnativewindow, libnativehelper, libjnigraphics, libbinder_ndk, libneuralnetworks, libwebviewchromium_plat_support.

VII Why not call host code directly?

Three reasons a proxy is unavoidable

The payoff is the whole performance story: the GPU never runs translated code. A Vulkan call crosses the proxy once, then the host graphics stack (GFXStream) and the real GPU do the heavy work at full native speed.

VII Inside a proxy call

Marshalling: four kinds of argument

"Marshalling" = repackaging data as it crosses the boundary. Real Vulkan calls show all four cases:

VII The honest edges

When a symbol can't be auto-bridged

Proxy call tables are largely auto-generated from library headers. Some signatures defeat automation — and the design principle is to fail loudly and precisely, never mysteriously:

• safety valve
  Unmappable symbols become tripwires. A symbol the generator can't marshal is stubbed to abort with its own name in the message — so a real app hitting it produces a one-line diagnosis, not a corrupted call.
• on demand
  Gaps are covered when real apps hit them. Hand-written trampolines fill each observed gap: JNI helpers, binder callbacks, WebView's hardware-acceleration hooks. Coverage is driven by evidence, not speculation.
• genuinely hard
  A few shapes stay out of reach. Variadic callbacks and functions returning unknown function-pointer types can't be safely bridged — those keep their loud stubs, documented.

VII The honest edges · vtables

When the API isn't symbols at all

Android's audio APIs (OpenSL ES, OpenMAX AL) hand the app a struct of function pointers — a vtable — and every call goes through it. There is no symbol to put in a call table; the proxy can only wrap each method lazily, by name, the moment the app first obtains the interface:

• the gap
  Methods the generator couldn't marshal became loaded guns. Each was registered as a loud abort-on-first-call stub under its wrap name — invisible to the symbol-table audit, because it never was a symbol. Nine callback registrations in OpenSL ES, and OpenMAX AL's whole interface-lookup dispatch, sat in that state.
• the seam
  Named overrides intercept at wrap time. A registry maps each wrap name to a working replacement; when the upstream layer registers its fatal stub, the replacement is installed instead — and the displaced upstream trampoline is recorded, so an override that only extends behaviour can delegate the rest back unchanged.
• the proof
  A host audio thread calls back into translated code. The probe registers the streaming-decode buffer-queue callback, feeds the decoder, and the callback fires — host code invoking a guest function mid-playback, the full round trip, not just a registration that returns success.

VII Syscall emulation · worked example

write(1, buf, 3), end to end

Libraries have proxies; the kernel gets a translation layer. Nothing lines up — different number register, different number value, different argument registers:

• inline, not bailed
  The JIT compiles SVC as a direct call into the syscall translator — system calls never detour through the interpreter.
• the non-change
  The buffer pointer crosses untouched — guest memory is host memory. Four things changed; the pointer deliberately did not.
• structs again
  Struct-shaped results (like stat) are repacked field by field on the way out, just as proxies do.

VII Syscalls · the long tail

Where real-app compatibility is won

Number remapping is the easy 95%. The last 5% is a collection of hard-won, very specific fixes — each one traced from a real app failing:

A theme worth noticing: none of these are "translate the instruction" problems — they're "be a convincing ARM64 Linux" problems. That's most of what shipping a translator actually is.

VII Beyond apps

binfmt_misc: the kernel joins in

Not everything arrives through an app. A shell command, a test binary, a subprocess spawned by execve() can also be ARM64. Linux's binfmt_misc lets the kernel recognize those and hand them to Digitalis automatically:

Complementary, not alternative — both paths share the same engine, cache, and proxies. Path B is what makes ARM64 test binaries and CI tools runnable on the emulator too.

VII binfmt_misc · under the hood

From execve() to the dispatch loop

• 1
  adb shell ./my-arm64-tool — the shell calls execve() on an ARM64 ELF.
• 2
  The kernel reads the file's first bytes and compares them against every entry registered in /proc/sys/fs/binfmt_misc/.
• 3
  The 19 magic bytes match (\x7fELF … machine 0xb7 = AArch64) — so the kernel silently rewrites the exec: it launches the registered interpreter instead, passing the original binary's path along. The P flag preserves argv[0], so the tool still sees its own name.
• 4
  That interpreter is berberis_program_runner_binfmt_misc_arm64 — a small x86_64 program that initializes the translator and asks the guest loader to start the ARM64 executable.
• 5
  From here it's the same machinery as an app: dispatch loop, JIT, interpreter, syscall layer, all 21 proxies. Only the front door differed.

Both trigger properties are set by the Digitalis product config, so registration needs no opt-in. A second runner binary exists for manual use — same engine, CLI-friendly arguments — which is how ARM64 gtest suites get run on the emulator during development.

VIII The main loop, dissected

Three execution paths, interleaved every frame

The launch itself is Part V verbatim: ART sees only arm64-v8a/, loads the bridge, the guest world is built, and a JNI trampoline enters android_main().

VIII Vulkan init · proxies in action

Building a GPU pipeline across the boundary

When the window appears, vulkan_init() fires a burst of proxy calls — each one marshalled guest → host, each returning a handle in X0:

From the host Vulkan driver's point of view, nothing unusual happened — it served a perfectly ordinary client. It cannot tell the client was ARM64.

VIII The render loop · every ~16ms

One frame at 60fps

VIII The expansion

What Digitalis adds to Berberis

Berberis supplied the architecture-neutral engine — cache, dispatch, assembler, exec regions, NativeBridge glue. Digitalis is the ARM64-shaped half that slots in beside it:

The distribution is concrete: ~74 files — one translator library, 21 proxies, ~43 guest ARM64 system libraries, two program runners, configs and magic files.

VIII How we know it works

The proof is the test suite

The samples span Vulkan, OpenGL ES, JNI, audio, camera, sensors, NEON/SIMD, CPU-extension probes, and real third-party engines — Qt, React Native, media and ML libraries — plus real prebuilt commercial apps as regression targets.

IX Question 1

"How fast is it, really?"

There's no single number — the honest answer is a profile. Speed depends on which path each piece of work takes:

The design keeps the multiplier where the time isn't: games spend their frames in the GPU and in hot cached loops — the two cheapest rows of this table. Measured anchors: GPU-bound 3DMark Wild Life Extreme scores 90% of the same machine's native run; pure-CPU Geekbench lands near one-fifth of native — and real apps live much closer to the first number than the second, because their frames are the first two rows.

IX Question 2

"Can the app tell? Can that break it?"

Digitalis works hard to be unobservable — and some apps work hard to observe. Both sides of that arms race, honestly:

• proof in the wild
  Real apps verified running under translation: full browsers (Firefox, Chromium-based Helium), the Unity-engine game Honkai: Star Rail, WeChat, WhatsApp, Facebook, Douyin, Kuaishou, NetEase Cloud Music, three major map apps (Amap, Baidu, Tencent), Qt's Vulkan Caps Viewer, React Native and Lynx-based UIs, plus 3DMark and Geekbench as benchmark workloads — seventeen commercial APKs — the games spanning Unity (Among Us), a custom native engine (Hill Climb Racing) and miHoYo’s (Honkai) — re-run as a regression gate on every change, several shipping aggressive integrity / anti-tamper SDKs.

When one of these breaks, the fix lands in the translator — never as a per-app hack — so each hardened app that starts working makes the next one likelier to work out of the box.

IX Question 3

"How do you debug code that never runs as written?"

A translated crash has two locations — the host instruction that faulted and the guest instruction it stands for. The tooling keeps both visible:

• tombstones
  Crash dumps speak ARM64. Android's crash reporter reads the guest registers out of ThreadState and prints X0–X30 — so a crash reads like it happened on a real ARM device.
• tracing
  A built-in flight recorder. A system property turns on per-app tracing: every region translated (with its guest address), dispatch activity, interpreter hot-spots — to a file or even a TCP socket, live.
• disassembly
  The guest PC is the anchor. Take the faulting guest address from the trace, disassemble the app's own .so at that offset, and you're looking at the exact ARM64 instruction that misbehaved.
• host tests
  Every bug becomes a unit test. A failing instruction gets a host-side test that feeds it through the real JIT and interpreter and compares full CPU state — including a differential fuzzer that diffs the two tiers against each other automatically.

IX Question 4

"Where are the limits?"

A fair summary: the hard 98% — running real apps' real code fast — is done and continuously verified; the remaining work is a curated list of known, bounded edges.

✦ In one breath

The whole idea, assembled

• why
  ARM64-only apps can't run on x86_64 emulators. Native .so code is CPU-specific; many apps ship ARM64 only.
• how
  Translate the app's machine code at runtime. JIT-compile regions on first sight, cache them forever, gear up the hot ones, interpret the rare tail.
• where
  Through Android's NativeBridge socket. The standard seam Houdini once filled — now filled openly, by Berberis.
• what
  Digitalis = the complete ARM64 backend for Berberis. Decoder, two-gear JIT, interpreter, syscall layer, and 21 proxy libraries over a shared open-source engine.
• proof
  150 sample apps, three tested tiers, real commercial apps. And a triangle, drawn at 60fps by a CPU that never saw the code it was given.