Baseline compilers

A quick compiler in the middle

A JavaScript engine is the program inside a browser or Node that runs your code. It does not run a function the same way forever. It has several tiers: steps that go from a quick start to fast code. A function starts on the first step. If it runs very often, it can move up. A function that runs very often is called hot.

On the first step, the interpreter runs bytecode. Bytecode is a simple list of small steps that the engine made from your code. The interpreter works like this, again and again:

1. It reads the next bytecode step.
2. It finds the piece of code that handles that kind of step. This is called dispatch.
3. It runs that piece of code.

The reading and finding take time on every step of every call. That extra time is the interpreter's overhead.

To compile means to turn code into another form before running it. Machine code is the form the computer's processor runs directly. A baseline compiler turns bytecode into simple machine code, and it does this quickly. The result is not the fastest code the engine can make. But now nothing has to read and look up each bytecode step on every call.

In the last lesson, inline caches, the engine saved facts about each operation in your code. Now the question is about cost. How much time should the engine spend compiling a function before that function has shown that it is hot? A baseline compiler's answer is "only a little."

This lesson stays on the baseline step. Tiered compilation showed all the steps. Optimizing compilers covers the strongest compilers, such as V8's TurboFan. A later lesson covers what happens when an optimizing compiler's guess turns out wrong.

V8 is the engine in Chrome and Node. Its interpreter is called Ignition. Its baseline compiler is called Sparkplug. Sparkplug does not read your JavaScript source. It starts from the bytecode that Ignition already made.

Most compilers first rebuild the program in their own private form. That form is called an intermediate representation, or IR. The IR helps a compiler study the code and change it, but building it takes time. V8's public article on Sparkplug says Sparkplug skips this. It turns each bytecode step straight into machine code.

1function stamp(total) {2  const fee = 2;3  return total + fee;4}5 6console.log(stamp(40));

Line 1 starts a function called stamp. Line 2 makes a local value, fee, set to 2. Line 3 adds the argument total to fee and returns the sum. Line 6 calls stamp(40) and prints 42.

Before the function runs, Ignition turns it into bytecode. Here is the bytecode Node prints for stamp. The lesson tests check these lines.

[generated bytecode for function: stamp]
LdaSmi [2]
Star0
Ldar r0
Add a0, [0]
Return

Two words first. A register is a numbered spot where the interpreter keeps a value. The accumulator is one special spot that holds the current result. In plain words, line by line:

1. Line 1 is a heading: the bytecode below belongs to stamp.
2. Line 2, LdaSmi [2], puts the small whole number 2 in the accumulator. "Smi" is short for "small integer".
3. Line 3, Star0, copies the accumulator into register 0. Register 0 is fee.
4. Line 4, Ldar r0, copies register 0 back into the accumulator.
5. Line 5, Add a0, [0], adds the first argument, a0, which is total. The [0] names feedback slot 0: the place where the engine keeps notes about the values this add has seen.
6. Line 6, Return, returns the value in the accumulator.

Some steps do complicated work, like an add that might get strings instead of numbers. For those, Sparkplug's machine code calls a builtin: a ready-made piece of machine code inside the engine that does one common job. Ignition calls the same builtins. That keeps Sparkplug small and quick.

The table below sums up how Sparkplug is built. Read each row as one part and what Sparkplug does there.

A template is a fixed piece of code with a blank to fill in. A template compiler keeps one template for each kind of bytecode step. For each step it reads, it copies the matching template and fills in the blank. Sparkplug works this way.

The code below is a small model in plain JavaScript. It does not look inside your browser's engine. The toy bytecode uses names like fee instead of register numbers, so it is easier to read. The output strings stand in for machine code.

1const bytecode = [2  ["LdaSmi", 2],3  ["Star", "fee"],4  ["Ldar", "fee"],5  ["Add", "total"],6  ["Return"],7];8 9function compileTemplates(bytecodes) {10  const machine = [];11  for (const instruction of bytecodes) {12    const [op, operand] = instruction;13    if (op === "LdaSmi") machine.push(`load_smi ${operand}`);14    if (op === "Star") machine.push(`store ${operand}`);15    if (op === "Ldar") machine.push(`load ${operand}`);16    if (op === "Add") machine.push(`add ${operand}`);17    if (op === "Return") machine.push("return accumulator");18  }19  return machine;20}21 22console.log(compileTemplates(bytecode).join(" | "));

In plain words, line by line:

1. Lines 1 to 7 hold the toy bytecode: five steps, the same five as the real bytecode for stamp.
2. Line 9 starts the compiler function, compileTemplates.
3. Line 10 makes an empty list, machine, for the output.
4. Line 11 goes through the steps in order, one at a time.
5. Line 12 splits each step into its name, op, and its value, operand.
6. Lines 13 to 17 check the name and add the matching template to the list.
7. Line 19 returns the list. Line 22 prints it with | between the templates: load_smi 2 | store fee | load fee | add total | return accumulator.

1const bytecode = [Run2  ["LdaSmi", 2],3  ["Star", "fee"],4  ["Ldar", "fee"],5  ["Add", "total"],6  ["Return"],7];8 9function compileTemplates(bytecodes) {10  const machine = [];11  for (const instruction of bytecodes) {12    const [op, operand] = instruction;13    if (op === "LdaSmi") machine.push(`load_smi ${operand}`);14    if (op === "Star") machine.push(`store ${operand}`);15    if (op === "Ldar") machine.push(`load ${operand}`);16    if (op === "Add") machine.push(`add ${operand}`);17    if (op === "Return") machine.push("return accumulator");18  }19  return machine;20}21 22console.log(compileTemplates(bytecode).join(" | "));

Notice what the compiler does not do. It never looks at the whole function at once. It does not join steps together or make guesses about the values. That is why it is fast. It is also why its code is not the fastest possible. The stronger compilers do that extra work later.

When a function is called, the engine sets up a stack frame for that call. A stack frame is a block of memory with fixed spots, called slots. Its slots hold:

• the function being run, and its context: the outer variables it can reach,
• the arguments,
• a few extra facts about the call, such as where it is in the bytecode,
• the registers,
• the way back to the code that made the call.

Sparkplug keeps its frames in the same shape as Ignition's frames. That matters, because many other parts of the engine read frames:

• the debugger, which shows you the variables when you pause,
• the profiler, which measures where the time goes,
• stack traces in error messages,
• on-stack replacement, or OSR: moving a function to another tier while it is still running, for example in the middle of a long loop.

Because the frames match, all of these keep working with Sparkplug code. They need little or no new code.

1const frame = {2  functionName: "stamp",3  context: "checkout",4  argument0: 40,5  bytecodeArray: "stamp bytecode",6  offsetOrFeedback: "bytecode offset 0",7  register0: undefined,8};9 10function runInIgnition(total) {11  frame.argument0 = total;12  frame.offsetOrFeedback = "bytecode offset 0";13  frame.register0 = 2;14  return frame.argument0 + frame.register0;15}16 17function runInSparkplug(total) {18  frame.argument0 = total;19  frame.offsetOrFeedback = "feedback vector";20  frame.register0 = 2;21  return frame.argument0 + frame.register0;22}23 24console.log(runInIgnition(40));25console.log(runInSparkplug(40));26console.log(frame.register0);

This is a small model of a frame. In plain words, line by line:

1. Lines 1 to 8 make one frame object. Each property stands for one slot.
2. Line 6, offsetOrFeedback, is the slot that the two tiers use in different ways.
3. Lines 10 to 15, runInIgnition, fill the slots the way the interpreter does. Line 12 puts a bytecode offset in the special slot. A bytecode offset is the position of the current step in the bytecode.
4. Lines 17 to 22, runInSparkplug, fill the same slots. Line 19 puts the feedback vector in that slot instead. The feedback vector is the list of notes the engine keeps for this function.
5. Lines 24 to 26 print 42, 42, and 2.

Sparkplug can still find the bytecode position when it needs it. It keeps a map from each place in its machine code back to the matching bytecode offset.

1const frame = {Run2  functionName: "stamp",3  context: "checkout",4  argument0: 40,5  bytecodeArray: "stamp bytecode",6  offsetOrFeedback: "bytecode offset 0",7  register0: undefined,8};9 10function runInIgnition(total) {11  frame.argument0 = total;12  frame.offsetOrFeedback = "bytecode offset 0";13  frame.register0 = 2;14  return frame.argument0 + frame.register0;15}16 17function runInSparkplug(total) {18  frame.argument0 = total;19  frame.offsetOrFeedback = "feedback vector";20  frame.register0 = 2;21  return frame.argument0 + frame.register0;22}23 24console.log(runInIgnition(40));25console.log(runInSparkplug(40));26console.log(frame.register0);

The table below shows why matching frames help. Read each row as one frame idea and what it means.

Other engines have baseline tiers too. SpiderMonkey is the engine in Firefox. Its documents list these tiers, in order:

1. a plain interpreter, written in C++,
2. the Baseline Interpreter,
3. the Baseline Compiler,
4. Warp and Ion, which together make the optimizing compiler.

The Baseline Interpreter is an interpreter that the engine itself made as machine code. Both baseline tiers use inline caches, or ICs: the small saved shortcuts for operations from the last lesson. The Baseline Compiler is a simple template compiler, like Sparkplug. It makes machine code for each script, and it uses the same ICs.

JavaScriptCore is the engine in Safari. Its public overview names four tiers in order: LLInt, Baseline JIT, DFG, and FTL. LLInt is the low-level interpreter. Baseline JIT is the quick compiler. DFG and FTL are the optimizing compilers; the next lesson covers them.

The table below puts the three engines side by side. Read each row as one engine, from its interpreter to its baseline tier.

A baseline compiler picks compile speed over code quality. Its code is not bad. It just skips slow, careful work until a function has shown that it is hot. Here are three kinds of work it usually skips:

• Inlining: copying a called function's body into the caller, so the call itself goes away.
• SSA form: rebuilding the whole function as a graph where each value is set only once, so it is easier to study. SSA stands for "static single assignment".
• Special code for each kind of value, such as code that only handles small whole numbers.

Its code still runs faster than the interpreter when a function runs again and again.

The table below compares the two kinds of compiler. Read each row as one question, answered for each one.

So baseline compilers fit the middle. Some code runs too often for the interpreter to be a good choice, but not often enough to pay for an optimizing compiler. If a function keeps running even more, the next lesson shows what the optimizing compilers do.

The playground below changes one input: how many times a function runs. The costs are made-up units, not real V8 numbers. Each tier has two costs:

• a compile cost, paid once: 0 for the interpreter, 12 for baseline, and 80 for the optimizer,
• a cost per call: 5 for the interpreter, 2 for baseline, and 0.7 for the optimizer.

The total is the compile cost plus the cost per call times the number of calls. The playground starts at 20 calls.

1function total(compileCost, callCost, calls) {2  return compileCost + callCost * calls;3}4 5for (const calls of [3, 20, 200]) {6  console.log(7    calls,8    total(0, 5, calls),9    total(12, 2, calls),10    total(80, 0.7, calls).toFixed(1),11  );12}

The buttons for 3, 20, and 200 calls are just samples. With these exact costs, baseline first costs less than the interpreter at 5 calls. The optimizer first costs less than baseline at 53 calls. Real engines decide with more facts: call counters, inline caches, notes about types, memory limits, and compiling on a background thread.

You can check some of these facts in Node, because Node uses V8. The lesson tests run Node 22, which comes with V8 12.4. They don't depend on exact version numbers, memory addresses, or timings. They check four things:

• the Sparkplug options exist,
• --print-bytecode prints the bytecode shown earlier,
• %CompileBaseline exists,
• after %CompileBaseline, V8's status for the function has the kBaseline bit turned on.

Words that start with %, like %CompileBaseline, are V8 native syntax. They are special test commands. They only work when Node starts with the --allow-natives-syntax option, and they are not normal JavaScript.

1// Run in Node with --allow-natives-syntax.2const bits = { kIsFunction: 1 << 0, kBaseline: 1 << 15 };3function stamp(total) {4  const fee = 2;5  return total + fee;6}7 8%CompileBaseline(stamp);9console.log(stamp(40));10const status = %GetOptimizationStatus(stamp);11console.log(Boolean(status & bits.kIsFunction));12console.log(Boolean(status & bits.kBaseline));

In plain words, line by line:

1. Line 1 says how to run the file.
2. Line 2 names two status bits. A status bit is one yes-or-no flag inside a number. kIsFunction is bit 0, and kBaseline is bit 15.
3. Lines 3 to 6 are the same stamp function as before.
4. Line 8 asks V8 to compile stamp with Sparkplug right now.
5. Line 9 prints 42.
6. Line 10 reads V8's status number for stamp.
7. Lines 11 and 12 use & to test one bit each. Both print true.

The next commands run the same kind of checks from a terminal.

node --v8-options | grep -E -- "--sparkplug|--always-sparkplug|--trace-baseline-batch-compilation|--print-bytecode"
node --print-bytecode --print-bytecode-filter=stamp stamp-probe.mjs
node --allow-natives-syntax --always-sparkplug baseline-status.mjs
node --allow-natives-syntax --no-sparkplug baseline-status.mjs

Line 1 lists V8's options and keeps only the four this lesson needs. Line 2 prints the bytecode for stamp. Line 3 runs a status check with Sparkplug used for every function. Line 4 runs the same check with Sparkplug turned off.

In day-to-day work, you rarely need to know whether a function runs in Sparkplug or in another engine's baseline tier. What helps is knowing three things:

• The first few runs of a function can be slower than later runs, because the engine has not compiled it yet. The later runs are called warm runs.
• A function that runs a medium amount can get faster in baseline code, without ever reaching the optimizer.
• Objects that keep the same shape, from the last lesson, still help the later tiers.

The table below turns this into advice. Read each row as one situation, what baseline compilers mean for it, and what to do.

Measure first. If something a user sees is slow, use a profiler, a tool that shows where the time goes, in the browser or Node process that runs it. Keep the code easy to read. Keep the data in hot code consistent. Use V8 native syntax only for experiments, never in real code.

Common misconceptions

The table below sums up ideas that are easy to mix up. Read each row as an idea, what it means, and what it does not mean.

Check your understanding

Answer these without guessing from the tier names. For a code question, work out what the code prints first. Then link it back to the idea from the lesson.

Key takeaways

• Sparkplug is V8's quick baseline compiler. It turns Ignition's bytecode straight into machine code, without building an IR first.
• Sparkplug's frames have the same slots as the interpreter's frames. So switching tiers, OSR, and the debugger keep working.
• SpiderMonkey and JavaScriptCore have their own baseline tiers. They do the same job, with different names and inner details.
• A baseline compiler gives up top speed to compile quickly. Measure real code before you change it for any compiler.

Next, Optimizing compilers shows what engines do when a function runs so often that it is worth spending more time on faster machine code. You'll meet Maglev, TurboFan, Warp, DFG, and FTL.