Bytecode & interpreters

What bytecode is

Before a JavaScript engine runs your code, it reads it. First it splits the text into words. Then it builds a tree that shows how the code fits together. This tree is called the AST, short for abstract syntax tree. Then it works out which variables belong to which function. That step is scope analysis.

A tree is good for describing code. It is slow to run directly. So the engine first turns the tree into a simpler form. That form is bytecode.

This lesson uses V8 as its main example. V8 is the engine inside Chrome and Node.js. Its interpreter is called Ignition. Near the end, you will compare it with the engines in Firefox and Safari.

Here is where this lesson fits among its neighbors:

• Before it: lazy parsing, which decides when each function is read.
• After it: startup snapshots and code caching, which save work between page loads.
• Later: tiered compilation, which makes busy code faster.

Machine code is the CPU's own language. The CPU is the computer's processor. An engine has three ways to run the tree:

• Walk the tree itself. This is simple to build. But the tree is made of many small objects that point at each other. That uses a lot of memory, and moving through it again and again is slow.
• Turn every function into machine code at once. Machine code runs fast. But making it takes time and memory. Much of the code that runs while a page loads runs only once, so that work is often wasted.
• Turn the tree into bytecode and run that. Bytecode is small and quick to make. Later, the engine can turn only the busy code into machine code.

V8 picked the third way. Its 2016 post, Firing up the Ignition interpreter, says Ignition bytecode is about a quarter to a half the size of the simple machine code V8 made before. V8 first turned Ignition on for Android phones with little memory.

The table compares four ways to run code. Each row says what actually runs, and what is good and bad about it.

While Ignition runs a function, it keeps values in two kinds of places:

• Registers are numbered slots that belong to one call of the function. They are not the CPU's own registers. They are slots in memory that Ignition sets aside. Parameters print as a0, a1, and so on. Local variables and in-between values print as r0, r1, and so on.
• The accumulator is one special slot for the value being worked on right now. Most instructions read from it, write to it, or both.

So many instructions use the accumulator that the listing does not name it. That keeps each instruction short.

Use this table to decode a V8 listing. The left column is what you see. The right column says what it means.

Here are three instructions, read in plain words:

• Ldar a0 means "copy parameter a0 into the accumulator".
• Star0 means "copy the accumulator into r0".
• Add r0, [1] means "add r0 to the accumulator". The [1] is not a number being added. It names feedback slot 1: the place where V8 notes what kinds of values this add sees.

The name of each instruction, like Ldar or Add, is called its opcode. The values after it are its operands. The table groups the opcodes in this lesson by the kind of job they do.

Node can print the bytecode V8 makes. The flag --print-bytecode turns printing on. The flag --print-bytecode-filter names one function, so only that function is printed.

This lesson's tests run the command below on the demo file. They check that every listing in this lesson still matches what Node prints. Memory addresses change on every run, so the listings show <addr> in their place.

1node --print-bytecode --print-bytecode-filter=loopSum bytecode-demo.js

1function arithmetic(a, b) {2  const total = a + b;3  return total * 2;4}5 6function propertyCall(user) {7  user.count = user.count + 1;8  return user.label(user.count);9}10 11function loopSum(n) {12  let total = 0;13  let i = 1;14  while (i < n) {15    total = total + i;16    i = i + 1;17  }18  return total;19}20 21function makeAdder(x) {22  return function add(y) {23    return x + y;24  };25}26 27function callFree(fn) {28  return fn(1, 2);29}30 31const user = { count: 1, label(value) { return "#" + value; } };32console.log(arithmetic(2, 3));33console.log(propertyCall(user));34console.log(loopSum(5));35console.log(makeAdder(4)(6));36console.log(callFree((a, b) => a + b));

Line by line: a loop

Here is the bytecode for loopSum, from lines 11 to 19 of the demo file. The first lines are facts about the function, not instructions:

• Parameter count 2: the function's this value plus its one parameter, n. V8 counts this as a parameter.
• Register count 2: two registers, r0 for total and r1 for i.

On each instruction line, the number after @ is the offset: how many bytes from the start of the bytecode the instruction sits. Jumps go to an offset, not to a source line.

1[generated bytecode for function: loopSum (<addr> <SharedFunctionInfo loopSum>)]2Bytecode length: 313Parameter count 24Register count 25Frame size 166  207 S> <addr> @    0 : 0c                LdaZero7         <addr> @    1 : c9                Star08  220 S> <addr> @    2 : 0d 01             LdaSmi [1]9         <addr> @    4 : c8                Star110  234 S> <addr> @    5 : 0b 03             Ldar a011  234 E> <addr> @    7 : 71 f8 00          TestLessThan r1, [0]12         <addr> @   10 : 9e 12             JumpIfFalse [18] (<addr> @ 28)13  245 S> <addr> @   12 : 0b f8             Ldar r114  259 E> <addr> @   14 : 3b f9 01          Add r0, [1]15         <addr> @   17 : c9                Star016  268 S> <addr> @   18 : 0b f8             Ldar r117  274 E> <addr> @   20 : 47 01 02          AddSmi [1], [2]18         <addr> @   23 : c8                Star119  225 E> <addr> @   24 : 8e 13 00 03       JumpLoop [19], [0], [3] (<addr> @ 5)20  285 S> <addr> @   28 : 0b f9             Ldar r021  298 S> <addr> @   30 : ae                Return22Constant pool (size = 0)23Handler Table (size = 0)24Source Position Table (size = 27)25<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

Read the loop part in order:

1. @ 5: Ldar a0 copies n into the accumulator.
2. @ 7: TestLessThan r1 checks whether i < n. The answer, true or false, goes into the accumulator.
3. @ 10: JumpIfFalse jumps out to offset 28 if the answer is false.
4. @ 12 to @ 17: copy i into the accumulator, add total, and store the sum back in r0.
5. @ 18 to @ 23: add 1 to i. In AddSmi [1], [2], the [1] is the number to add, and [2] is a feedback slot. Smi is short for "small integer".
6. @ 24: JumpLoop goes back to offset 5 to test again.

Properties, calls, and closures

Reading and writing a property each have their own opcode in V8 12.4:

• GetNamedProperty reads a property, like user.count.
• SetNamedProperty writes a property, like user.count = 2.
• CallProperty1 calls a method with one argument, like user.label(user.count). It names the function, the object before the dot, the argument, and a feedback slot.

1[generated bytecode for function: propertyCall (<addr> <SharedFunctionInfo propertyCall>)]2Bytecode length: 273Parameter count 24Register count 35Frame size 246  124 S> <addr> @    0 : 2f 03 00 01       GetNamedProperty a0, [0], [1]7  130 E> <addr> @    4 : 47 01 00          AddSmi [1], [0]8  117 E> <addr> @    7 : 35 03 00 03       SetNamedProperty a0, [0], [3]9  149 S> <addr> @   11 : 2f 03 01 05       GetNamedProperty a0, [1], [5]10         <addr> @   15 : c9                Star011  160 E> <addr> @   16 : 2f 03 00 01       GetNamedProperty a0, [0], [1]12         <addr> @   20 : c7                Star213  149 E> <addr> @   21 : 61 f9 03 f7 07    CallProperty1 r0, a0, r2, [7]14  167 S> <addr> @   26 : ae                Return15Constant pool (size = 2)16<addr>: [TrustedFixedArray]17 - map: <addr> <Map(TRUSTED_FIXED_ARRAY_TYPE)>18 - length: 219           0: <addr> <String[5]: #count>20           1: <addr> <String[5]: #label>21Handler Table (size = 0)22Source Position Table (size = 18)23<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

Line 6 reads user.count. In GetNamedProperty a0, [0], [1], the [0] points to entry 0 of the constant pool. That is the list of fixed values at the bottom of the listing, and entry 0 is the name count. Line 8 writes the new count. Line 13 calls label as a method.

Closures link back to scope analysis. A closure is a function that keeps using variables from the function around it. Here, the inner add uses x from makeAdder. So makeAdder keeps x in a context: a small object for variables that inner functions need.

1[generated bytecode for function: makeAdder (<addr> <SharedFunctionInfo makeAdder>)]2Bytecode length: 143Parameter count 24Register count 15Frame size 86  320 E> <addr> @    0 : 88 00 01          CreateFunctionContext [0], [1]7         <addr> @    3 : 1a f9             PushContext r08         <addr> @    5 : 0b 03             Ldar a09         <addr> @    7 : 25 02             StaCurrentContextSlot [2]10  328 S> <addr> @    9 : 85 01 00 02       CreateClosure [1], [0], #211  375 S> <addr> @   13 : ae                Return12Constant pool (size = 2)13<addr>: [TrustedFixedArray]14 - map: <addr> <Map(TRUSTED_FIXED_ARRAY_TYPE)>15 - length: 216           0: <addr> <ScopeInfo FUNCTION_SCOPE>17           1: <addr> <SharedFunctionInfo add>18Handler Table (size = 0)19Source Position Table (size = 10)20<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

Line 6 makes the context. Line 9 stores x in slot 2 of that context. Line 10, CreateClosure, makes the inner add function.

1[generated bytecode for function: add (<addr> <SharedFunctionInfo add>)]2Bytecode length: 93Parameter count 24Register count 15Frame size 86  357 S> <addr> @    0 : 17 02             LdaImmutableCurrentContextSlot [2]7         <addr> @    2 : c9                Star08         <addr> @    3 : 0b 03             Ldar a09  366 E> <addr> @    5 : 3b f9 00          Add r0, [0]10  370 S> <addr> @    8 : ae                Return11Constant pool (size = 0)12Handler Table (size = 0)13Source Position Table (size = 9)14<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

Line 6 reads x back from the context, and line 7 stores it in r0. Line 8 copies y into the accumulator. Line 9 adds them.

A plain call such as fn(1, 2) has no object before the dot. V8 calls the this value of a call its receiver. So for this call it prints CallUndefinedReceiver2: a call with no receiver and two arguments.

1[generated bytecode for function: callFree (<addr> <SharedFunctionInfo callFree>)]2Bytecode length: 123Parameter count 24Register count 35Frame size 246   26 S> <addr> @    0 : 0d 01             LdaSmi [1]7         <addr> @    2 : c8                Star18         <addr> @    3 : 0d 02             LdaSmi [2]9         <addr> @    5 : c7                Star210   33 E> <addr> @    6 : 66 03 f8 f7 00    CallUndefinedReceiver2 a0, r1, r2, [0]11   42 S> <addr> @   11 : ae                Return12Constant pool (size = 0)13Handler Table (size = 0)14Source Position Table (size = 8)15<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

The opcode only says how the call is written. Inside the called function, the usual rules for this still apply. The code below shows both rules.

1function sloppyReceiver() {2  return this === globalThis;3}4 5function strictReceiver() {6  "use strict";7  return this === undefined;8}9 10console.log(sloppyReceiver());11console.log(strictReceiver());

Both lines print true. Outside strict mode, a plain call gets the global object, globalThis, as this. In strict mode, this stays undefined.

The experiments below use a small model, not V8. Here is what the model does:

1. It reads a tiny function with acorn, a library that builds the AST.
2. It turns the AST into toy bytecode that uses an accumulator and registers, like Ignition.
3. It runs the toy bytecode with a table of small functions, one for each opcode.

The model knows only a few things. It has no objects, no errors, and none of V8's speed tricks. Its opcodes have names like V8's, but they are not real V8 bytecode.

Each toy instruction has a number, starting at 0. A counter called pc, short for program counter, holds the number of the next instruction to run. Most instructions add 1 to pc. Jumps set pc to another number.

1const program = [2  ["LdaSmi",0],Run3  ["Star","r0"],4  ["LdaSmi",1],5  ["Star","r1"],6  ["Ldar","r1"],7  ["Star","r2"],8  ["Ldar","a0"],9  ["Star","r3"],10  ["LdaSmi",1],11  ["Add","r3"],12  ["TestLessThan","r2"],13  ["JumpIfFalse",23],14  ["Ldar","r0"],15  ["Star","r4"],16  ["Ldar","r1"],17  ["Add","r4"],18  ["Star","r0"],19  ["Ldar","r1"],20  ["Star","r5"],21  ["LdaSmi",1],22  ["Add","r5"],23  ["Star","r1"],24  ["Jump",4],25  ["Ldar","r0"],26  ["Return"],27];28 29function run(bytecode, a0) {30  const registers = { a0: a0, r0: undefined, r1: undefined };31  let pc = 0;32  let acc;33  const dispatch = {34    LdaSmi(value) { acc = value; pc += 1; },35    Ldar(register) { acc = registers[register]; pc += 1; },36    Star(register) { registers[register] = acc; pc += 1; },37    Add(register) { acc = registers[register] + acc; pc += 1; },38    Mul(register) { acc = registers[register] * acc; pc += 1; },39    TestLessThan(register) { acc = registers[register] < acc; pc += 1; },40    JumpIfFalse(target) { pc = acc ? pc + 1 : target; },41    Jump(target) { pc = target; },42    Return() { pc = bytecode.length; },43  };44  while (pc < bytecode.length) {45    const [op, operand] = bytecode[pc];46    dispatch[op](operand);47  }48  return acc;49}50 51console.log(run(program, 4));

Watch the loop. JumpIfFalse leaves the loop when the accumulator holds false. Jump sets pc back to 4, where the loop test starts. Back and Reset replay steps saved from a real run of the model.

1const program = [2  ["Ldar","a0"],Run3  ["Star","r1"],4  ["LdaSmi",2],5  ["Mul","r1"],6  ["Star","r0"],7  ["Ldar","r0"],8  ["Star","r2"],9  ["LdaSmi",1],10  ["Add","r2"],11  ["Return"],12];13 14function run(bytecode, a0) {15  const registers = { a0: a0, r0: undefined };16  let pc = 0;17  let acc;18  const dispatch = {19    LdaSmi(value) { acc = value; pc += 1; },20    Ldar(register) { acc = registers[register]; pc += 1; },21    Star(register) { registers[register] = acc; pc += 1; },22    Add(register) { acc = registers[register] + acc; pc += 1; },23    Mul(register) { acc = registers[register] * acc; pc += 1; },24    TestLessThan(register) { acc = registers[register] < acc; pc += 1; },25    JumpIfFalse(target) { pc = acc ? pc + 1 : target; },26    Jump(target) { pc = target; },27    Return() { pc = bytecode.length; },28  };29  while (pc < bytecode.length) {30    const [op, operand] = bytecode[pc];31    dispatch[op](operand);32  }33  return acc;34}35 36console.log(run(program, 5));

This shorter example makes the accumulator easy to follow. Load a value. Store it in a register. Load the next value. Combine the two. Return the result. Real V8 has more kinds of opcodes, but the idea is the same: one value being worked on, plus numbered slots for saved values.

Now try your own. Pick an example, change the argument, or edit the function. Then compare the toy bytecode with a real V8 listing for a similar function.

0000 LdaSmi 0
0001 Star r0
0002 LdaSmi 1
0003 Star r1
0004 Ldar r1
0005 Star r2
0006 Ldar a0
0007 Star r3
0008 LdaSmi 1
0009 Add r3
0010 TestLessThan r2
0011 JumpIfFalse 23
0012 Ldar r0
0013 Star r4
0014 Ldar r1
0015 Add r4
0016 Star r0
0017 Ldar r1
0018 Star r5
0019 LdaSmi 1
0020 Add r5
0021 Star r1
0022 Jump 4
0023 Ldar r0
0024 Return

[generated bytecode for function: loopSum (<addr> <SharedFunctionInfo loopSum>)]
Bytecode length: 31
Parameter count 2
Register count 2
Frame size 16
  207 S> <addr> @    0 : 0c                LdaZero
         <addr> @    1 : c9                Star0
  220 S> <addr> @    2 : 0d 01             LdaSmi [1]
         <addr> @    4 : c8                Star1
  234 S> <addr> @    5 : 0b 03             Ldar a0
  234 E> <addr> @    7 : 71 f8 00          TestLessThan r1, [0]
         <addr> @   10 : 9e 12             JumpIfFalse [18] (<addr> @ 28)
  245 S> <addr> @   12 : 0b f8             Ldar r1
  259 E> <addr> @   14 : 3b f9 01          Add r0, [1]
         <addr> @   17 : c9                Star0
  268 S> <addr> @   18 : 0b f8             Ldar r1
  274 E> <addr> @   20 : 47 01 02          AddSmi [1], [2]
         <addr> @   23 : c8                Star1
  225 E> <addr> @   24 : 8e 13 00 03       JumpLoop [19], [0], [3] (<addr> @ 5)
  285 S> <addr> @   28 : 0b f9             Ldar r0
  298 S> <addr> @   30 : ae                Return
Constant pool (size = 0)
Handler Table (size = 0)
Source Position Table (size = 27)
<addr> <Other heap object (TRUSTED_BYTE_ARRAY_TYPE)>

The interpreter does not understand opcode names by itself. Each opcode has its own small piece of code that does that opcode's job. That piece of code is called a handler. Running bytecode is a short cycle:

1. Read the opcode at the current offset.
2. Go to that opcode's handler. This step is called dispatch.
3. The handler does its job. It changes the accumulator, a register, or the program counter.
4. Repeat with the next opcode.

1const handlers = {2  LdaSmi(state, value) {3    state.acc = value;4    state.pc += 1;5  },6  Add(state, register) {7    state.acc = state.registers[register] + state.acc;8    state.pc += 1;9  },10  JumpIfFalse(state, target) {11    state.pc = state.acc ? state.pc + 1 : target;12  },13};14 15function dispatch(bytecode, state) {16  const [op, operand] = bytecode[state.pc];17  return handlers[op](state, operand);18}

Lines 1 to 13 build handlers, an object with one function for each opcode. Line 6 starts the Add handler. Line 15 starts dispatch. Line 16 reads the instruction at pc: its opcode name and its operand. Line 17 picks the handler by that name and runs it.

Ignition does the same thing in machine code. V8's docs call it threaded dispatch:

• Each handler is its own small block of machine code.
• At its end, a handler reads the next opcode. It looks up that opcode's handler in a table and jumps straight there.

V8 did not write these handlers by hand for every kind of CPU. Its first Ignition post says they were made with the back end of TurboFan, the compiler V8 uses for its fastest machine code. Later V8 tools, such as the CodeStubAssembler, use the same back end to build other small pieces of machine code.

The bytecode itself is kept small too. Copying the accumulator into a low-numbered register has its own one-byte opcode: Star0, Star1, Star2, and so on. You can see them in the Node 22 listings above. Like the unnamed accumulator, these short opcodes make the bytecode smaller.

Bytecode is small, but it still uses memory. V8's V8 Lite project measured real web pages. Bytecode and feedback were two of the big users of memory. Several V8 Lite ideas are now part of normal V8.

Two words first:

• A feedback vector is one function's list of feedback slots: its notes about what kinds of values each operation saw.
• Garbage collection (GC) is when the engine frees memory that nothing uses any more.

Each row of the table is one way V8 saves memory around bytecode.

You can see these settings in Node today:

• --flush-bytecode is on by default.
• --lazy-feedback-allocation is on by default.
• --invocation-count-for-feedback-allocation sets one of the limits that decide when a function gets its feedback vector.

These are details inside the engine. Your app code should not depend on them.

The JavaScript standard does not say what bytecode looks like. Each engine makes its own. Firefox's engine, SpiderMonkey, and Safari's engine, JavaScriptCore (JSC), also run bytecode first. Their bytecode looks different, and they decide in their own ways when to move code to a faster tier.

Each row is one engine: the name of its first tier, and what its bytecode looks like.

A little more about each one:

• SpiderMonkey's first tier is the Baseline Interpreter. Firefox's docs call it a mix of an interpreter and a JIT. A JIT, or just-in-time compiler, makes machine code while the program runs. The Baseline Interpreter runs bytecode one opcode at a time. It also attaches inline caches: small saved shortcuts that make repeated operations faster.
• SpiderMonkey's bytecode uses a stack, a pile of values. Each opcode's description says how many values it takes off the pile and how many it puts back.
• JSC's bytecode names its slots inside each instruction, such as loc7 for a local variable and arg1 for an argument. Its first tier is the LLInt, short for Low Level Interpreter. WebKit wrote it in offlineasm, a small assembly-like language of its own.

You don't need bytecode for most speed problems. Start with these tools first:

• the browser's Performance panel
• speed numbers from real users
• a look at how big your JavaScript files are
• the call stack

Bytecode helps in a few cases. Each row of the table is a question you might have, and when bytecode can answer it.

Common misconceptions

• “Bytecode is JavaScript with shorter names.” It is a separate list of instructions. Each engine makes its own, after it has parsed your code and worked out its scopes.
• “Bytecode is machine code.” The CPU cannot run Ignition bytecode. Handlers carry out each instruction, or a compiler turns the bytecode into machine code.
• “One V8 listing teaches every browser.” SpiderMonkey and JavaScriptCore have their own bytecode, with different opcode names.
• “A number in brackets is always a value.” In Add r0, [1], the [1] names a feedback slot. It is not the number 1.
• “Flushing bytecode changes what my program does.” It only saves memory. If the function runs again, V8 makes its bytecode again.

Each row names two ideas that are easy to mix up, then says how they differ.

Key takeaways

• Bytecode is a short list of instructions. It sits between the AST and the CPU's machine code.
• Ignition keeps values in registers and in one accumulator. Most instructions use the accumulator without naming it.
• --print-bytecode shows offsets, registers, constants, and feedback slots for one V8 version.
• An interpreter is a cycle: read an opcode, go to its handler, let the handler do its job, repeat.
• V8 can throw away old bytecode and make feedback vectors late to save memory. Your program behaves the same.
• SpiderMonkey and JavaScriptCore also run bytecode first, but their bytecode and first tiers are their own.

Next: Startup: snapshots & code caching. Later, Tiered compilation shows how busy bytecode moves on to faster tiers.