Builtins on Opensource internals

Code Stub Assembler: How V8 Writes Machine Code by Hand

Jay Hubbert — Fri, 23 Oct 2026 09:40:00 +0000

TL;DR: The Code Stub Assembler is not an assembler. CodeStubAssembler (src/codegen/code-stub-assembler.h) does not emit a single byte - it builds a TurboFan graph, and TurboFan’s per-architecture backend turns that graph into machine code. That is the entire reason the same builtin source compiles to x64, arm64 and ia32 unchanged. Underneath it sit three more layers: the byte-level Assembler (one class per architecture), the MacroAssembler on top of it, and the compiler::RawMachineAssembler, which is the graph builder that CSA actually talks to.

The mistake everybody makes first

The name is the problem. “Code Stub Assembler” sounds like movq(rax, rbx) with a type annotation, and it is not. Compare the two layers:

 cpp
 
 
// src/codegen/x64/assembler-x64.h:639
class V8_EXPORT_PRIVATE Assembler : public AssemblerBase {
 private:
 // We check before assembling an instruction that there is sufficient
 // space to write an instruction and its relocation information.

That is the byte layer: one method per x86 instruction, one file per architecture. src/codegen/x64/assembler-x64.h, src/codegen/arm64/assembler-arm64.h and src/codegen/ia32/assembler-ia32.h each declare their own class Assembler : public AssemblerBase.

The Code Stub Assembler is somewhere else entirely:

 cpp
 
 
// src/codegen/code-stub-assembler.h:66
// Provides JavaScript-specific "macro-assembler" functionality on top of the
// CodeAssembler. By factoring the JavaScript-isms out of the CodeAssembler,
// it's possible to add JavaScript-specific useful CodeAssembler "macros"
// without modifying files in the compiler directory (and requiring a review
// from a compiler directory OWNER).
class V8_EXPORT_PRIVATE CodeStubAssembler
 : public compiler::CodeAssembler,
 public TorqueGeneratedExportedMacrosAssembler {

compiler::CodeAssembler is the graph builder, and it says so:

 cpp
 
 
// src/compiler/code-assembler.h:387
// A "public" interface used by components outside of compiler directory to
// create code objects with TurboFan's backend. This class is mostly a thin
// shim around the RawMachineAssembler, and its primary job is to ensure that
// the innards of the RawMachineAssembler and other compiler implementation
// details don't leak outside of the compiler directory.

And the thing underneath that is a graph too:

 cpp
 
 
// src/compiler/raw-machine-assembler.h:36
// The RawMachineAssembler produces a low-level IR graph. All nodes are wired
// into a graph and also placed into a schedule immediately, hence subsequent
// code generation can happen without the need for scheduling.
//
// In order to create a schedule on-the-fly, the assembler keeps track of basic
// blocks by having one current basic block being populated and by referencing
// other basic blocks through the use of labels.

So the real stack, bottom to top, is:

text

 TurboFan backend (x64 / arm64 / ia32 / ...) -> machine bytes
 compiler::RawMachineAssembler -> low-level IR graph
 compiler::CodeAssembler -> public, typed graph API
 CodeStubAssembler (CSA) -> JS-flavoured graph API
 Torque -> generates C++ that calls CSA

The byte-level Assembler and MacroAssembler are a different branch of the tree. They are used by hand-written assembly builtins, by Sparkplug, by Maglev, and by the runtime’s own stubs. They never see a TurboFan graph. If you are reading a builtin that is listed as ASM(...) in src/builtins/builtins-definitions.h, it is in that branch, and it exists precisely because it needs to manipulate the stack in ways that TurboFan’s fixed frame layout cannot express.

What CSA adds on top

Two things.

First, JavaScript types. TNode<Smi>, TNode<JSArray>, TNode<Context>, TNode<NativeContext> are C++ types, so the compiler catches Smi + String at compile time. TNode<AnyTaggedT> is the escape hatch.

Second, JavaScript semantics: allocating a HeapObject, loading a field off a Map, checking an elements kind, reading a Context slot. None of that lives in compiler::CodeAssembler, which is organised around machine types rather than around V8’s object model.

The dividing line between “graph API” and “JavaScript API” is visible in where the Call helpers live. compiler::CodeAssembler has the generic ones:

 cpp
 
 
// src/compiler/code-assembler.h:1399
 // Calls
 template <class T = Object, class... TArgs>
 TNode<T> CallRuntime(Runtime::FunctionId function, TNode<Object> context,
 TArgs... args) {
 return UncheckedCast<T>(CallRuntimeImpl(
 function, context, {implicit_cast<TNode<Object>>(args)...}));
 }

and CodeStubAssembler adds the JavaScript-specific ones on top: CallBuiltin, CallJS, CallFunction, Allocate, TaggedEqual, LoadMap, and so on.

One source, three architectures

The portability is not magic and it is not in CSA at all. It comes from the fact that CSA is a graph API, so TurboFan’s per-architecture instruction selector and code generator do the final lowering. V8 ships those backends under src/compiler/backend/, one directory per architecture: x64/, arm64/, ia32/, arm/, ppc/, riscv/, s390/, mips64/, loong64/.

What CSA does own is the set of decisions that have to look the same on every architecture. Two of them are interesting.

The first is CPU feature detection. Some instructions are not available everywhere, so CSA emits a branch on a unique constant - a constant the graph optimiser cannot fold - and provides a software fallback:

 cpp
 
 
// src/codegen/code-stub-assembler.cc:440
TNode<Float64T> CodeStubAssembler::Float64Ceil(TNode<Float64T> x) {
 TVARIABLE(Float64T, var_x, x);
 Label round_op_supported(this), round_op_fallback(this), return_x(this);
 // Use UniqueInt32Constant instead of BoolConstant here in order to ensure
 // that the graph structure does not depend on the value of the predicate
 // (BoolConstant uses cached nodes).
 Branch(UniqueInt32Constant(IsFloat64RoundUpSupported()), &round_op_supported,
 &round_op_fallback);

 BIND(&round_op_supported);
 {
 // This optional operation is used behind a static check and we rely
 // on the dead code elimination to remove this unused unsupported
 // instruction. We generate builtins this way in order to ensure that
 // builtins PGO profiles are interchangeable between architectures.
 var_x = Float64RoundUp(x);
 Goto(&return_x);
 }

That comment is the whole portability story in miniature: the shape of the graph must not depend on the machine, or the same builtin would have a different PGO profile on x64 and on arm64 and the profiles could not be shipped in a snapshot.

The second is data representation. Smi might be 31 or 32 bits depending on the pointer-compression configuration; a tagged pointer might be 4 or 8 bytes. CSA never asks. It asks for SmiAdd(a, b) and the answer is correct because the graph node has a MachineRepresentation that was chosen at build time.

TaggedEqual: the cost of comparing two objects

This is the smallest interesting function in the file:

 cpp
 
 
// src/codegen/code-stub-assembler.h:299
 TNode<BoolT> TaggedEqual(TNode<AnyTaggedT> a, TNode<AnyTaggedT> b,
 SourceLocation loc = SourceLocation::Current()) {
#if defined(V8_EXTERNAL_CODE_SPACE) || defined(V8_ENABLE_SANDBOX)
 if (v8_flags.enable_slow_asserts) {
 CheckObjectComparisonAllowed(a, b, loc);
 }
#endif
 if (COMPRESS_POINTERS_BOOL) {
 return Word32Equal(ReinterpretCast<Word32T>(a),
 ReinterpretCast<Word32T>(b));
 } else {
 return WordEqual(ReinterpretCast<WordT>(a), ReinterpretCast<WordT>(b));
 }
 }

Two things to notice. First, it is a word comparison, not a call to Object::Equals: comparing two references for identity is a machine instruction, and Torque’s TaggedEqual (used, for example, to test whether an IC slot holds the megamorphic symbol) inherits that. Second, it is the place where the sandbox’s rules bite: under V8_ENABLE_SANDBOX, comparing two objects that live in different pointer compression cages is illegal, so there is a separate SafeEqual for objects that may legitimately live in different cages:

 cpp
 
 
// src/codegen/code-stub-assembler.h:319
 // A variant of TaggedEqual which allows comparing objects in different
 // pointer compression cages. In particular, this should be used when
 // comparing objects in trusted- or code space with objects in the main
 // pointer compression cage. Currently only defined for HeapObject, this
 // type can be expanded if needed.
 TNode<BoolT> SafeEqual(TNode<HeapObject> a, TNode<HeapObject> b) {

The distinction between TaggedEqual and SafeEqual is the kind of detail that produces a sandbox bug report months later.

The helpers that matter

CallRuntime - call a C++ runtime function. The implementation shows the whole trampoline: the runtime call goes through the RuntimeCEntry builtin, with the runtime function’s address passed as an external constant:

 cpp
 
 
// src/compiler/code-assembler.cc:1298
 Builtin centry =
 Builtins::RuntimeCEntry(result_size, switch_to_the_central_stack);
 TNode<Code> centry_code =
 HeapConstantNoHole(isolate()->builtins()->code_handle(centry));
 constexpr size_t kMaxNumArgs = 7;
 DCHECK_GE(kMaxNumArgs, args.size());
 int argc = static_cast<int>(args.size());
 auto call_descriptor = Linkage::GetRuntimeCallDescriptor(
 zone(), function, argc, Operator::kNoProperties,
 Runtime::MayAllocate(function) ? CallDescriptor::kNoFlags
 : CallDescriptor::kNoAllocate);

 TNode<ExternalReference> ref =
 ExternalConstant(ExternalReference::Create(function));
 TNode<Int32T> arity = Int32Constant(argc);

 NodeArray<kMaxNumArgs + 4> inputs;
 inputs.Add(centry_code);
 for (const auto& arg : args) inputs.Add(arg);
 inputs.Add(ref);
 inputs.Add(arity);
 inputs.Add(context);

 CallPrologue();
 Node* return_value =
 raw_assembler()->CallN(call_descriptor, inputs.size(), inputs.data());
 HandleException(return_value);
 CallEpilogue();
 return return_value;

Runtime::MayAllocate(function) picks the call descriptor flags, which tells the garbage collector whether this call site can trigger a GC. That is the kind of metadata that is easy to get wrong by hand and free to get right in one place.

TailCallRuntime is the same thing without a return: it is a jump, so the frame does not grow.

CallCFunction is for calling a raw C++ function pointer, without the runtime-call machinery:

 cpp
 
 
// src/compiler/code-assembler.cc:1590
Node* CodeAssembler::CallCFunction(
 Node* function, std::optional<MachineType> return_type,
 std::initializer_list<CodeAssembler::CFunctionArg> args) {
 return raw_assembler()->CallCFunction(function, return_type, args);
}

CallBuiltin is how one builtin calls another. It is worth reading because the call descriptor is not a constant - it is looked up from the builtin id:

 cpp
 
 
// src/compiler/code-assembler.h:1439
 template <typename T = Object, class... TArgs>
 TNode<T> CallBuiltin(Builtin id, TNode<Object> context, TArgs... args) {
 DCHECK_WITH_MSG(!Builtins::HasJSLinkage(id), "Use CallJSBuiltin instead");
 TNode<RawPtrT> old_sp;
#if V8_ENABLE_WEBASSEMBLY
 bool maybe_needs_switch = wasm::BuiltinLookup::IsWasmBuiltinId(builtin()) &&
 !wasm::BuiltinLookup::IsWasmBuiltinId(id);
 if (maybe_needs_switch) {
 old_sp = SwitchToTheCentralStackIfNeeded();
 }
#endif
 Callable callable = Builtins::CallableFor(isolate(), id);
 TNode<Code> target = HeapConstantNoHole(callable.code());
 TNode<T> call =
 CallStub<T>(callable.descriptor(), target, context, args...);

The DCHECK_WITH_MSG is a real constraint, not decoration: a JS-linkage builtin has a different calling convention (an argument count, a dispatch handle, a new target) and must be called with CallJSBuiltin instead.

Allocate is the bump-pointer allocator with a runtime escape hatch. This is the single most instructive function in CSA:

 cpp
 
 
// src/codegen/code-stub-assembler.cc:1656
 TNode<Smi> runtime_flags = SmiConstant(
 Smi::FromInt(needs_double_alignment ? kDoubleAligned : kTaggedAligned));
 result =
 CallRuntime(Runtime::kAllocateInYoungGeneration, NoContextConstant(),
 SmiTag(size_in_bytes), runtime_flags);
 Goto(&out);

 BIND(&next);
 }

 TVARIABLE(IntPtrT, adjusted_size, size_in_bytes);

and then the fast path:

 cpp
 
 
// src/codegen/code-stub-assembler.cc:1679
 TNode<IntPtrT> new_top =
 IntPtrAdd(UncheckedCast<IntPtrT>(top), adjusted_size.value());

 Branch(UintPtrGreaterThanOrEqual(new_top, limit), &runtime_call,
 &no_runtime_call);

So: load the current top and the limit from the heap, add the (aligned) size, and if the new top would cross the limit, take the slow path and ask the runtime to allocate. The size is checked to be a positive Smi first, which is why the slow path only ever sees sane sizes.

What a CSA builtin looks like

The TF_BUILTIN macro is the harness. It builds a small assembler class whose Descriptor is the generated interface descriptor, and it wires the builtin into Builtins::Generate_<Name>:

 cpp
 
 
// src/builtins/builtins-utils-gen.h:31
#define TF_BUILTIN(Name, AssemblerBase) \
 class Name##Assembler : public AssemblerBase { \
 public: \
 using Descriptor = Builtin_##Name##_InterfaceDescriptor; \
 \
 explicit Name##Assembler(compiler::CodeAssemblerState* state) \
 : AssemblerBase(state) {} \
 void Generate##Name##Impl(); \
 \
 template <class T> \
 TNode<T> Parameter( \
 Descriptor::ParameterIndices index, \
 cppgc::SourceLocation loc = cppgc::SourceLocation::Current()) { \
 return CodeAssembler::Parameter<T>(static_cast<int>(index), loc); \
 } \
 \
 template <class T> \
 TNode<T> UncheckedParameter(Descriptor::ParameterIndices index) { \
 return CodeAssembler::UncheckedParameter<T>(static_cast<int>(index)); \
 } \
 }; \
 void Builtins::Generate_##Name(compiler::CodeAssemblerState* state) { \
 Name##Assembler assembler(state); \
 state->SetInitialDebugInformation(#Name, __FILE__, __LINE__); \
 if (Builtins::KindOf(Builtin::k##Name) == Builtins::TFJ) { \
 assembler.PerformStackCheck(assembler.GetJSContextParameter()); \
 } \
 assembler.Generate##Name##Impl(); \
 } \
 void Name##Assembler::Generate##Name##Impl()

Two details in there are worth more than the whole macro. The parameter index comes from Descriptor::ParameterIndices, i.e. from the generated call descriptor, so the implementation cannot disagree with the calling convention. And the stack check is inserted automatically for JS-linkage builtins (TFJ), because a JS builtin can recurse and must check the stack limit on entry.

A complete CSA builtin is then tiny:

 cpp
 
 
// src/builtins/builtins-handler-gen.cc:46
TF_BUILTIN(LoadIC_StringLength, CodeStubAssembler) {
 auto string = Parameter<String>(Descriptor::kReceiver);
 Return(LoadStringLengthAsSmi(string));
}

TF_BUILTIN(LoadIC_StringWrapperLength, CodeStubAssembler) {
 auto value = Parameter<JSPrimitiveWrapper>(Descriptor::kReceiver);
 TNode<String> string = CAST(LoadJSPrimitiveWrapperValue(value));
 Return(LoadStringLengthAsSmi(string));
}

CAST is a compile-time checked cast, not a runtime branch. The CheckedNode template static_asserts that the cast is legal at all (“Incompatible types: this cast can never succeed.”) and, in debug builds only, calls ExternalReference::check_object_type() to verify the instance type. If you want a runtime check, you write the GotoIfNot yourself; UncheckedCast skips even the static_assert.

From CSA source to a Code object

The builtin table is generated by the same macro machinery that generates the Torque builtin list, and there are three kinds of builtin that matter here:

 cpp
 
 
// src/builtins/builtins.h:643
#define DECLARE_ASM(Name, ...) \
 static void Generate_##Name(MacroAssembler* masm);
#define DECLARE_TF(Name, ...) \
 static void Generate_##Name(compiler::CodeAssemblerState* state);
#define DECLARE_TS(Name, ...) \
 static void Generate_##Name(compiler::turboshaft::PipelineData* data, \
 Isolate* isolate, \
 compiler::turboshaft::Graph& graph, Zone* zone);

DECLARE_TF is CSA. DECLARE_ASM is the byte-level branch. DECLARE_TS is the new Turboshaft branch, which is where V8 is heading.

At start-up, src/builtins/setup-builtins-internal.cc walks the whole list. CSA builtins are handed to TurboFan as compilation jobs:

 cpp
 
 
// src/builtins/setup-builtins-internal.cc:518
#define BUILD_TFJ_WITH_JOB(Name, Argc, ...) \
 CompileJSLinkageCodeStubBuiltin(isolate, Builtin::k##Name, \
 &Builtins::Generate_##Name, \
 install_generated_builtin, Argc, #Name, \
 job_creation_order++, scheduler);

while the assembly ones are built directly into a buffer:

 cpp
 
 
// src/builtins/setup-builtins-internal.cc:564
#define BUILD_ASM_WITHOUT_JOB(Name, InterfaceDescriptor) \
 code = BuildWithMacroAssembler(isolate, Builtin::k##Name, \
 Builtins::Generate_##Name, #Name); \
 generated_builtins[Builtins::ToInt(Builtin::k##Name)] = \
 handle(code, isolate); \
 builtins_built_without_job_count++;

The two paths converge on the same thing: a Code object with a builtin id, installed into the isolate’s table.

 cpp
 
 
// src/builtins/setup-builtins-internal.cc:604
 // Add the generated builtins to the isolate.
 for (Builtin builtin = Builtins::kFirst; builtin <= Builtins::kLast;
 ++builtin) {
 AddBuiltin(builtins, builtin,
 *generated_builtins[Builtins::ToInt(builtin)]);
 }

The scale of this is worth a number. The checked-in generated builtin list for one configuration (src/gen/intl-wasm/builtin-definitions.h) contains 358 TFJ entries and 395 TFC entries - roughly 750 builtins whose calling conventions are all derived from a single signature each.

The bytes of that code live in the code space, which is a heap space with its own allocator and its own GC rules:

 cpp
 
 
// src/heap/factory.cc:281
 result =
 heap->heap()->allocator()->AllocateRawWith<HeapAllocator::kRetryOrFail>(
 object_size, AllocationType::kCode, AllocationOrigin::kRuntime);

AllocationType::kCode is the important bit. Code is not in the young generation, it is not moved by the scavenger, and it is written and then made immutable.

Keeping the debugger honest

A CSA builtin is machine code that nobody wrote by hand, so the debugger needs a way to map an instruction pointer back to something a human wrote. Two mechanisms do that.

The first is a source position attached to the graph nodes. The API is deliberately explicit about whose source positions these are:

 cpp
 
 
// src/compiler/code-assembler.h:830
 // The following methods refer to source positions in CSA or Torque code
 // compiled during mksnapshot, not JS compiled at runtime.
 void SetSourcePosition(const char* file, int line);

The Torque backend fills those in, one line per Torque statement, and converts from Torque’s zero-based lines to the one-based lines the rest of V8 uses:

 cpp
 
 
// src/torque/csa-generator.cc:92
void CSAGenerator::EmitSourcePosition(SourcePosition pos, bool always_emit) {
 const std::string& file = SourceFileMap::AbsolutePath(pos.source);
 if (always_emit || !previous_position_.CompareStartIgnoreColumn(pos)) {
 // Lines in Torque SourcePositions are zero-based, while the
 // CodeStubAssembler and downwind systems are one-based.
 out() << " ca_.SetSourcePosition(\"" << file << "\", "
 << (pos.start.line + 1) << ");\n";
 previous_position_ = pos;
 }
}

The previous_position_ check is an optimisation, and a nice one: the position is only re-emitted when the line changes, not when the column does, so a long basic block does not pay for a source position per statement.

The second is the initial debug information, which is what shows up in a stack trace when a builtin throws:

 cpp
 
 
// src/builtins/builtins-utils-gen.h:52
 void Builtins::Generate_##Name(compiler::CodeAssemblerState* state) { \
 Name##Assembler assembler(state); \
 state->SetInitialDebugInformation(#Name, __FILE__, __LINE__); \

__FILE__ and __LINE__ here are the generated file and line, not the Torque source. The Torque source position is what the graph nodes carry; this is the fallback for the frames that have no graph node to point at.

The inline cache handlers are CSA too

The property-access ICs are builtins, and their implementations are CSA. src/builtins/builtins-definitions.h lists them under a TFH (“handlers in Turbofan, with CodeStub linkage”):

 cpp
 
 
// src/builtins/builtins-definitions.h:869
 TFH(LoadIC, LoadWithVector) \
 TFH(LoadIC_Megamorphic, LoadWithVector) \
 TFH(LoadIC_Noninlined, LoadWithVector) \
 TFH(LoadICTrampoline, Load) \

and each one is a Builtins::Generate_* function that constructs a CSA subclass:

 cpp
 
 
// src/builtins/builtins-ic-gen.cc:17
void Builtins::Generate_LoadIC(compiler::CodeAssemblerState* state) {
 AccessorAssembler assembler(state);
 assembler.GenerateLoadIC();
}
void Builtins::Generate_LoadIC_Megamorphic(
 compiler::CodeAssemblerState* state) {
 AccessorAssembler assembler(state);
 assembler.GenerateLoadIC_Megamorphic();
}

AccessorAssembler (src/ic/accessor-assembler.h) is a CodeStubAssembler subclass, and it is where the megamorphic stub-cache probe lives:

 cpp
 
 
// src/ic/accessor-assembler.cc:4840
void AccessorAssembler::GenerateLoadIC_Megamorphic() {
 using Descriptor = LoadWithVectorDescriptor;

 auto receiver = Parameter<JSAny>(Descriptor::kReceiver);
 auto name = Parameter<Object>(Descriptor::kName);
 auto slot = Parameter<TaggedIndex>(Descriptor::kSlot);
 auto vector = Parameter<HeapObject>(Descriptor::kVector);
 auto context = Parameter<Context>(Descriptor::kContext);

 ExitPoint direct_exit(this);
 TVARIABLE(MaybeObject, var_handler);
 Label if_handler(this, &var_handler), miss(this, Label::kDeferred);

and the miss goes to a runtime:

 cpp
 
 
// src/ic/accessor-assembler.cc:4882
 BIND(&miss);
 direct_exit.ReturnCallRuntime(Runtime::kLoadIC_Miss, context, receiver, name,
 slot, vector);

So the inline cache story has two halves: the interpreter and TurboFan patch the site, and the handler that runs on a miss is a CSA builtin. The LoadIC_Miss runtime then re-runs the lookup in C++ and installs a new handler.

Two different “handler tables”

Worth disambiguating, because the phrase means two things in V8.

The IC handler is what we just described: a Code object selected by the feedback vector. There is no table; the feedback slot holds a Smi that encodes the handler.

The handler table (src/codegen/handler-table.h) is something else entirely - it is the exception-handler table of a code object:

 cpp
 
 
// src/codegen/handler-table.h:25
// HandlerTable is a byte array containing entries for exception handlers in
// the code object it is associated with. The tables come in two flavors:
// 1) Based on ranges: Used for unoptimized code. Stored in a
// {TrustedByteArray} that is attached to each {BytecodeArray}. Contains one
// entry per exception handler and a range representing the try-block covered
// by that handler. Layout looks as follows:
// [ range-start , range-end , handler-offset , handler-data ]
// 2) Based on return addresses: Used for turbofanned code. Stored directly in
// the instruction stream of the {InstructionStream} object. Contains one
// entry per call-site that could throw an exception. Layout looks as
// follows:
// [ return-address-offset , handler-offset ]

The second flavour is the interesting one: for TurboFan-generated code there is no try/catch structure, so V8 reconstructs one at unwind time by scanning backwards from the return address. Every call site that could throw has an entry.

Trade-offs

What CSA buys.

One source per builtin, nine architectures. The x64, arm64 and ia32 backends exist to lower the graph; the builtin source does not change.
A real type system. TNode<Smi> and TNode<String> cannot be mixed.
The TurboFan optimiser for free. Because CSA produces a graph, dead code elimination, register allocation and instruction scheduling all apply to builtins. A hand-written assembly builtin gets none of that.
Cheap cross-language calls. CallCFunction lets a builtin call into C++ without going through the full runtime-call protocol.

What CSA costs.

It is not an assembler. You cannot see the instructions. When something is slow there is no objdump to look at, and the only way to reason about the output is to dump the TurboFan graph.
It is a graph, so it is slower to generate. A builtin that is generated at every isolate start-up pays graph construction cost. That is why V8 embeds builtins in the binary, and why there is a “short builtin calls” mechanism that remaps the embedded blob into the isolate’s code range so generated code can reach it with a short PC-relative call.
Two layers of the same idea. Assembler/MacroAssembler and CodeAssembler/CodeStubAssembler both exist, and the choice between them is per builtin. The comment in docs/builtins/architecture.md is blunt about it: architecture-specific builtins “must be used for any operations that need to manipulate the stack … because TurboFan code assumes a fixed stack layout”.
A third backend is coming. DECLARE_TS in the same macro block is the Turboshaft assembler, and CSA is on the way out.

The bottom line

Think of CSA as a typed, JavaScript-aware, architecture-neutral intermediate language that happens to be written in C++. The API is deliberately small: build a graph of loads, stores, branches and calls; let TurboFan lower it; let the per-architecture backend emit bytes.

The mental model to keep is that a CSA builtin is not “assembly that happens to be portable”. It is a program in a graph language, and the portability is a consequence of never touching bytes yourself.

The thing people get wrong

The common misreading is that CSA is an abstraction over machine instructions, so that a CSA builtin compiles to roughly the same instructions everywhere. It does not. CSA is an abstraction over a TurboFan graph, so a CSA builtin is optimised. Concretely: a CSA builtin gets dead-code elimination, constant folding, register allocation and instruction scheduling; a MacroAssembler builtin gets none of those, because it is already bytes by the time anybody can look at it.

The second misreading is that CSA and the MacroAssembler are two spellings of the same thing. They are two different branches of the tree with different performance characteristics and different rules about what you may do - most importantly, only the MacroAssembler branch can manipulate the stack, because TurboFan-generated code assumes a fixed frame layout.

For the language that generates most of V8’s builtins, see Torque: The DSL V8 Uses to Write Its Own Builtins.

Torque: The DSL V8 Uses to Write Its Own Builtins

Jay Hubbert — Fri, 23 Oct 2026 09:10:00 +0000

TL;DR: Torque is a small, strongly typed DSL that V8 wrote so that Array.prototype.map could be read like the ECMAScript spec instead of like a C++ template. A .tq file is parsed into an AST (src/torque/torque-parser.cc), type-checked and lowered into a control flow graph of Torque IR instructions (src/torque/instructions.h), and then translated into C++ that calls the Code Stub Assembler (src/torque/csa-generator.cc). The same run also emits the builtin table and the call descriptors, so the calling convention of ArrayMapLoopContinuation is derived from its Torque signature rather than written by hand twice.

Why V8 needed a second language

V8 has four ways to write a builtin, and each one is wrong in a different direction.

A C++ builtin is a plain function called through the runtime-call mechanism. It is easy to write and it is slow: every call crosses a C++ boundary, and the arguments have to be unpacked out of a stack frame.

An assembly builtin is written with the per-architecture MacroAssembler. It is as fast as it can be, and it has to be written once per architecture - V8 currently ships x64, arm64, ia32, arm, ppc, s390, riscv, mips64 and loong64 backends.

A Code Stub Assembler builtin is portable, because CSA emits a TurboFan graph rather than bytes, but it is verbose and its type system is C++ templates rather than something the compiler can reason about.

Torque is the fourth, and it sits on top of CSA. It adds the thing CSA was missing: a type system that knows about Smi, JSArray, Context and NativeContext as distinct types, that refuses to let you add a String to a Number, and that can prove a Cast<T>(x) otherwise Bailout actually succeeded. The payoff is visible in the source: a Torque builtin reads like the specification, with the spec’s step numbers still in the comments.

The pipeline, in the order the compiler runs it

The whole driver is short enough to read in one sitting. CompileCurrentAst in src/torque/torque-compiler.cc is the top of the pipeline:

 cpp
 
 
// src/torque/torque-compiler.cc:82
 // Two-step process of predeclaration + resolution allows to resolve type
 // declarations independent of the order they are given.
 PredeclarationVisitor::Predeclare(GlobalContext::ast());
 PredeclarationVisitor::ResolvePredeclarations();

 // Process other declarations.
 DeclarationVisitor::Visit(GlobalContext::ast());

 // A class types' fields are resolved here, which allows two class fields to
 // mutually refer to each others.
 TypeOracle::FinalizeAggregateTypes();

Predeclaration exists so that type declarations can be resolved in any order - the comment above it says the point is “to resolve type declarations independent of the order they are given”, and the comment below adds that “a class types’ fields are resolved here, which allows two class fields to mutually refer to each others”. Then DeclarationVisitor walks the AST once more and resolves macros, builtins and constants - and this is where overload resolution happens, using the type oracle to answer “is Smi a subtype of Number?”.

After that, the ImplementationVisitor turns declarations into implementations and emits every artifact the rest of V8 needs:

 cpp
 
 
// src/torque/torque-compiler.cc:112
 ImplementationVisitor implementation_visitor;
 implementation_visitor.SetDryRun(output_directory.empty());

 implementation_visitor.GenerateInstanceTypes(output_directory);
 implementation_visitor.BeginGeneratedFiles();
 implementation_visitor.BeginDebugMacrosFile();

 implementation_visitor.VisitAllDeclarables();

 ReportAllUnusedMacros();

 implementation_visitor.GenerateBuiltinDefinitionsAndInterfaceDescriptors(
 output_directory);

Note ReportAllUnusedMacros(): a Torque macro that nobody calls is reported by the compiler (Lint("Macro '...' is never used.")), which is how the language stays honest about its own dead code.

The output is three files per .tq input:

 cpp
 
 
// src/torque/implementation-visitor.cc:1959
 // TODO(torque-builder): Pass file directly.
 WriteFile(base_filename + "-tq-csa.cc", std::move(csa_cc));
 WriteFile(base_filename + "-tq-csa.h", streams.csa_headerfile.str());

 WriteFile(base_filename + "-tq.cc", streams.class_definition_ccfile.str());

-tq-csa.cc is the CSA implementation, -tq-csa.h the declarations other generated files need, and -tq.cc is a completely different backend: it emits C++ class definitions and debug readers for the structs that Torque declares, so a Torque struct Vector has a real C++ mirror.

The IR: twenty-two instructions, all of them boring on purpose

Between the AST and the backend sits a tiny typed IR. The instruction set is listed in one place, which makes it easy to see how small the surface area is:

 cpp
 
 
// src/torque/instructions.h:34
#define TORQUE_BACKEND_DEPENDENT_INSTRUCTION_LIST(V) \
 V(PushUninitializedInstruction) \
 V(PushBuiltinPointerInstruction) \
 V(LoadReferenceInstruction) \
 V(StoreReferenceInstruction) \
 V(LoadBitFieldInstruction) \
 V(StoreBitFieldInstruction) \
 V(CallCsaMacroInstruction) \
 V(CallIntrinsicInstruction) \
 V(NamespaceConstantInstruction) \
 V(CallCsaMacroAndBranchInstruction) \
 V(CallBuiltinInstruction) \
 V(CallRuntimeInstruction) \
 V(CallBuiltinPointerInstruction) \
 V(BranchInstruction) \
 V(ConstexprBranchInstruction) \
 V(GotoInstruction) \
 V(GotoExternalInstruction) \
 V(MakeLazyNodeInstruction) \
 V(ReturnInstruction) \
 V(PrintErrorInstruction) \
 V(AbortInstruction) \
 V(UnsafeCastInstruction)

There is no arithmetic instruction, no comparison instruction, no loop instruction. A Torque if becomes a BranchInstruction plus blocks; a Torque + becomes a CallCsaMacroInstruction for the Add CSA macro. Torque deliberately has no expression semantics of its own - it is a control flow language whose leaves are CSA calls.

That is the key design decision, and it explains the rest of the architecture. Because every leaf is a CSA macro, the backends only have to know how to translate twenty-two instructions.

The keywords that actually matter

The grammar is an Earley parser built out of Rules. Six keywords carry most of the meaning.

extern marks a declaration with no Torque body: the implementation lives in hand-written C++ (usually CSA) and Torque only knows its signature.

 cpp
 
 
// src/torque/torque-parser.cc:2928
 Rule({annotations, Token("extern"), CheckIf(Token("transitioning")),
 Optional<std::string>(
 Sequence({Token("operator"), &externalString})),
 Token("macro"),
 Optional<std::string>(Sequence({&identifier, Token("::")})), &name,
 TryOrDefault<GenericParameters>(&genericParameters),
 &typeListMaybeVarArgs, &returnType, optionalLabelList, Token(";")},
 MakeExternalMacro),
 Rule({annotations, Token("extern"), CheckIf(Token("transitioning")),
 CheckIf(Token("javascript")), Token("builtin"), &name,
 TryOrDefault<GenericParameters>(&genericParameters),
 &typeListMaybeVarArgs, &returnType, Token(";")},
 MakeExternalBuiltin),

transitioning is the interesting one. A transitioning callable may run arbitrary JavaScript, allocate, or move the heap around underneath you. The type system uses it to invalidate transient types - types such as FastJSArray that are only valid as long as nothing has run in between. Using a transient value across a transitioning call is a type error, and the enforcement is explicit: after a transitioning call, every transient type still on the value stack is replaced by a poison type that carries the error message with it.

 cpp
 
 
// src/torque/instructions.cc:138
void InstructionBase::InvalidateTransientTypes(
 Stack<const Type*>* stack) const {
 auto current = stack->begin();
 while (current != stack->end()) {
 if ((*current)->IsTransient()) {
 std::stringstream stream;
 stream << "type " << **current
 << " is made invalid by transitioning callable invocation at "
 << PositionAsString(pos);
 *current = TypeOracle::GetTopType(stream.str(), *current);
 }
 ++current;
 }
}

and it is called only when the callee is transitioning:

 cpp
 
 
// src/torque/instructions.cc:166
 if (intrinsic->IsTransitioning()) {
 InvalidateTransientTypes(stack);
 }
 stack->PushMany(LowerType(intrinsic->signature().return_type));
}

javascript marks a builtin with the JS calling convention, so it can be called from JavaScript code.

builtin distinguishes a real builtin - which gets its own Code object and its own entry in the builtin table - from a macro, which is inlined into its caller at the Torque level. A macro is a compile-time function; a builtin is a runtime function.

namespace groups declarations so that they are not visible outside the namespace, and it maps straight onto a C++ namespace in the generated file:

 cpp
 
 
// src/torque/torque-parser.cc:2974
 Rule({Token("namespace"), &identifier, Token("{"), &declarationList,
 Token("}")},
 AsSingletonVector<Declaration*, MakeNamespaceDeclaration>())};

js-implicit context is the calling convention for a JS-linkage builtin. The parser distinguishes implicit from js-implicit explicitly:

 cpp
 
 
// src/torque/torque-parser.cc:529
 if (implicit_params->kind->value == "implicit") {
 result.implicit_kind = ImplicitKind::kImplicit;
 } else {
 DCHECK_EQ(implicit_params->kind->value, "js-implicit");
 result.implicit_kind = ImplicitKind::kJSImplicit;
 }

The difference matters: a js-implicit builtin receives the context, receiver, target and newTarget slots of the JavaScript calling convention, and the context it receives is a NativeContext, not a generic Context. V8 builtins always embed the native context in their closures, so making the type NativeContext lets the compiler drop a load.

A builtin, end to end

Here is the whole of ArrayMapLoopContinuation, which is the slow path of Array.prototype.map:

torque

// src/builtins/array-map.tq:62
transitioning builtin ArrayMapLoopContinuation(
 implicit context: Context)(_receiver: JSReceiver, callbackfn: Callable,
 thisArg: JSAny, array: JSReceiver, o: JSReceiver, initialK: Number,
 length: Number): JSAny {
 // 6. Let k be 0.
 // 7. Repeat, while k < len
 for (let k: Number = initialK; k < length; k++) {
 // 7a. Let Pk be ! ToString(k).
 // k is guaranteed to be a positive integer, hence ToString is
 // side-effect free and HasProperty/GetProperty do the conversion inline.

 // 7b. Let kPresent be ? HasProperty(O, Pk).
 const kPresent: Boolean = HasProperty_Inline(o, k);

 // 7c. If kPresent is true, then:
 if (kPresent == True) {
 // i. Let kValue be ? Get(O, Pk).
 const kValue: JSAny = GetProperty(o, k);

 // ii. Let mapped_value be ? Call(callbackfn, T, kValue, k, O).
 const mappedValue: JSAny =
 Call(context, callbackfn, thisArg, kValue, k, o);

 // iii. Perform ? CreateDataPropertyOrThrow(A, Pk, mapped_value).
 FastCreateDataProperty(array, k, mappedValue);
 }

 // 7d. Increase k by 1. (done by the loop).
 }

 // 8. Return A.
 return array;
}

Note Call(context, callbackfn, thisArg, kValue, k, o) - that is the Call extern macro, and the call into user JavaScript happens right there. We will come back to it.

Now the lowering. The ImplementationVisitor emits a TF_BUILTIN wrapper for every builtin, and turns the implicit parameters into real CSA parameter loads:

 cpp
 
 
// src/torque/implementation-visitor.cc:666
 csa_ccfile() << "TF_BUILTIN(";
 size_t begin = static_cast<size_t>(csa_ccfile().tellp());
 csa_ccfile() << name;
 size_t end = static_cast<size_t>(csa_ccfile().tellp());
 if (GlobalContext::has_kythe_inline_metadata() &&
 CurrentFileStreams::HasScope()) {
 const SourcePosition ident_pos = builtin->IdentifierPosition();
 if (auto* streams = CurrentFileStreams::Get();
 streams && ident_pos.IsValid()) {
 streams->csa_cc_rules.push_back(
 GlobalContext::KytheInlineMetadata::CallAnchor(
 begin, end, static_cast<size_t>(ident_pos.start.offset),
 static_cast<size_t>(ident_pos.end.offset),
 KytheSourceFilePath(ident_pos.source)));
 }
 }
 csa_ccfile() << ", CodeStubAssembler) {\n"
 << " compiler::CodeAssemblerState* state_ = state();"
 << " compiler::CodeAssembler ca_(state());\n";

The same function then walks the signature and emits one UncheckedParameter<T>(Descriptor::kX) per argument. The Descriptor:: constants come from the generated interface descriptor, so the parameter indices in the generated C++ are the same numbers the descriptor uses - there is no second, hand-maintained list.

For a varargs JS builtin the prologue is longer, because the arguments live on the stack and have to be walked:

 cpp
 
 
// src/torque/implementation-visitor.cc:701
 csa_ccfile() << " TNode<Word32T> argc = UncheckedParameter<Word32T>("
 << "Descriptor::kJSActualArgumentsCount);\n";
 csa_ccfile() << " TNode<IntPtrT> "
 "arguments_length(ChangeInt32ToIntPtr(UncheckedCast<"
 "Int32T>(argc)));\n";
 csa_ccfile() << " TNode<RawPtrT> arguments_frame = "
 "UncheckedCast<RawPtrT>(LoadFramePointer());\n";

The interesting bit is LoadFramePointer(): the builtin reads its arguments off the stack through the frame pointer, with the frame’s own argument count deciding how many there are. That is why the js-implicit convention can have a variable number of arguments without allocating an array.

How a macro call becomes a CSA call

The CSA backend turns each IR instruction into a string of C++. For a Torque-defined macro the generated call looks like a normal C++ call; for an extern macro it is a call on a freshly constructed CodeStubAssembler:

 cpp
 
 
// src/torque/csa-generator.cc:351
 if (ExternMacro* extern_macro = ExternMacro::DynamicCast(instruction.macro)) {
 out() << extern_macro->external_assembler_name() << "(state_).";
 } else {
 args.insert(args.begin(), "state_");
 }
 out() << instruction.macro->ExternalName() << "(";
 PrintCommaSeparatedList(out(), args);

The assembler name defaults to CodeStubAssembler:

 cpp
 
 
// src/torque/torque-parser.cc:621
 result = {MakeNode<ExternalMacroDeclaration>(
 transitioning,
 external_assembler_name ? *external_assembler_name
 : "CodeStubAssembler",
 name, operator_name, args, return_type, std::move(labels))};

So extern transitioning macro Call(Context, JSAny, JSAny): JSAny; becomes, in the generated file, a call to CodeStubAssembler(state_).Call(context, callable, receiver).

A call to a Torque builtin is different: it is not inlined, it is a real call to the builtin’s Code object:

 cpp
 
 
// src/torque/csa-generator.cc:591
 if (result_types.empty()) {
 out() << "ca_.CallBuiltinVoid(Builtin::k"
 << instruction.builtin->ExternalName();
 } else {
 out() << " " << lhs_name << " = ";
 out() << "ca_.CallBuiltin<" << lhs_type << ">(Builtin::k"
 << instruction.builtin->ExternalName();
 }

And a runtime call goes through the runtime-function table:

 cpp
 
 
// src/torque/csa-generator.cc:743
 out() << " " << result_name << " = ";
 if (generated_type != "Object") out() << "TORQUE_CAST(";
 out() << "CodeStubAssembler(state_).CallRuntime(Runtime::k"
 << instruction.runtime_function->ExternalName() << ", ";

And TORQUE_CAST is not a checked cast. It expands to a trusted cast, and the source is candid about why:

 cpp
 
 
// src/compiler/code-assembler.h:608
 // Currently casts from torque are unconditionally trusted.
#ifdef DEBUG
#define STRINGIFY(x) #x
#define TO_STRING_LITERAL(x) STRINGIFY(x)
#define CAST(x) \
 Cast(x, "CAST(" #x ") at " __FILE__ ":" TO_STRING_LITERAL(__LINE__))
#define TORQUE_CAST(...) \
 /* TODO: Should we trust all torque types? */ \
 ca_.TrustedCastImpl(__VA_ARGS__, "CAST(" #__VA_ARGS__ ") at " __FILE__ \
 ":" TO_STRING_LITERAL(__LINE__))
#else
#define CAST(x) Cast(x)
#define TORQUE_CAST(...) ca_.TrustedCastImpl(__VA_ARGS__)
#endif

In other words, the check that TORQUE_CAST skips is exactly the check the Torque type system is supposed to have already proved. When you write Cast<JSArray>(x) otherwise Bailout, the type checker makes sure the bailout is reachable; the generated C++ then trusts the result. The TODO: Should we trust all torque types? is the maintainers admitting that this is a promise, not a proof.

Context slots: a typed layout

Torque describes the NativeContext layout in the same file that describes the object, src/objects/contexts.tq, and it makes the slot type part of the index:

torque

// src/objects/contexts.tq:107
macro ContextSlot<ArgumentContext: type, AnnotatedContext: type, T: type>(
 context: ArgumentContext, index: Slot<AnnotatedContext, T>):&T {
 const context: AnnotatedContext = context;
 return torque_internal::unsafe::ReferenceCast<T>(&context.elements[index]);
}

macro NativeContextSlot<T: type>(
 context: NativeContext, index: Slot<NativeContext, T>):&T {
 return ContextSlot(context, index);
}

The index type is Slot<NativeContext, T>, so a slot that is declared to hold a Map can only be read as a Map. The enum itself is in the same file:

torque

// src/objects/contexts.tq:126
extern enum ContextSlot extends intptr constexpr 'Context::Field' {
 SCOPE_INFO_INDEX: Slot<Context, ScopeInfo>,
 // Zero is used for the NativeContext, Undefined is used for synthetic
 // function contexts.
 PREVIOUS_INDEX: Slot<Context, Context|Zero|Undefined>,

 AGGREGATE_ERROR_FUNCTION_INDEX: Slot<NativeContext, JSFunction>,
 ARRAY_BUFFER_FUN_INDEX: Slot<NativeContext, Constructor>,

constexpr 'Context::Field' names the C++ enum that supplies the constants, so the Torque declaration and the C++ Context::Field enum are the same values by construction rather than by convention. A NativeContext slot and a Context slot are different types, so you cannot accidentally read a native-context slot out of a function context.

From a builtin to a Code object and a JSFunction

Two separate things happen, and it is worth keeping them apart.

First, the compiler emits the table. The checked-in copy of the generated header is in the tree:

 c
 
 
// src/gen/intl-wasm/builtin-definitions.h:60
TFJ(ArrayMapPreLoopLazyDeoptContinuation, JSParameterCount(4), kReceiver, kCallback, kThisArg, kLength, kResult) \
TFJ(ArrayMapLoopEagerDeoptContinuation, JSParameterCount(5), kReceiver, kCallback, kThisArg, kArray, kInitialK, kLength) \
TFJ(ArrayMapLoopLazyDeoptContinuation, JSParameterCount(6), kReceiver, kCallback, kThisArg, kArray, kInitialK, kLength, kResult) \
TFC(ArrayMapLoopContinuation, ArrayMapLoopContinuation) \
TFJ(ArrayMap, kDontAdaptArgumentsSentinel) \

TFJ is “Torque function with JS linkage”; TFC is “Torque function with CodeStub linkage”. The parameter names in the TFJ line are not documentation - they are the generated descriptor’s parameter names, and they are exactly the names the Torque source used.

For a stub builtin the compiler also emits a call descriptor, into a separate .inc file:

 c
 
 
// src/gen/intl-wasm/interface-descriptors.inc:145
class ArrayMapLoopContinuationDescriptor : public StaticCallInterfaceDescriptor<ArrayMapLoopContinuationDescriptor> {
 public:
 INTERNAL_DESCRIPTOR()
 SANDBOXING_MODE(kSandboxed)
 DEFINE_RESULT_AND_PARAMETERS(1, kReceiver, kCallbackfn, kThisArg, kArray, kO, kInitialK, kLength)
 DEFINE_RESULT_AND_PARAMETER_TYPES(MachineType::AnyTagged(), MachineType::TaggedPointer(), MachineType::TaggedPointer(), MachineType::AnyTagged(), MachineType::TaggedPointer(), MachineType::TaggedPointer(), MachineType::AnyTagged(), MachineType::AnyTagged())
 DECLARE_DEFAULT_DESCRIPTOR(ArrayMapLoopContinuationDescriptor)
};

The number of parameters, their names and their machine types all come from the Torque signature. Nobody writes the argument order down twice.

Second, each builtin becomes a Code object - either generated at isolate start-up or deserialized from the embedded blob that V8 ships in the binary. src/builtins/setup-builtins-internal.cc drives the whole builtin list with one macro per kind:

 cpp
 
 
// src/builtins/setup-builtins-internal.cc:518
#define BUILD_TFJ_WITH_JOB(Name, Argc, ...) \
 CompileJSLinkageCodeStubBuiltin(isolate, Builtin::k##Name, \
 &Builtins::Generate_##Name, \
 install_generated_builtin, Argc, #Name, \
 job_creation_order++, scheduler);

Builtins::Generate_##Name is the C++ function that the Torque backend emitted, and install_generated_builtin puts the resulting Code into the isolate’s builtin table. The code object itself is a CodeKind::BUILTIN:

 c
 
 
// src/objects/code-kind.h:19
#define CODE_KIND_LIST(V) \
 V(BYTECODE_HANDLER) \
 V(FOR_TESTING) \
 V(FOR_TESTING_JS) \
 V(BUILTIN) \
 V(REGEXP) \

Third, the JavaScript-visible function object. A builtin does not become a JSFunction by itself; the bootstrapper creates one and installs it on a prototype:

 cpp
 
 
// src/init/bootstrapper.cc:953
Handle<JSFunction> SimpleInstallFunction(Isolate* isolate,
 DirectHandle<JSObject> base,
 const char* name, Builtin call,
 int len, AdaptArguments adapt,
 PropertyAttributes attrs) {
 // Although function name does not have to be internalized the property name
 // will be internalized during property addition anyway, so do it here now.
 DirectHandle<String> internalized_name =
 isolate->factory()->InternalizeUtf8String(name);
 Handle<JSFunction> fun =
 SimpleCreateFunction(isolate, internalized_name, call, len, adapt);
 JSObject::AddProperty(isolate, base, internalized_name, fun, attrs);
 return fun;
}

So Array.prototype.map is a JSFunction whose SharedFunctionInfo points at Builtin::kArrayMap, and the builtin’s Code object is the implementation. The two are joined by the builtin id, not by a pointer.

There is no `Redirection` builtin

Older write-ups of V8 mention a Redirection trampoline. Grep the current tree and you will not find one: Redirection survives in V8 only as the name of the simulator’s external-reference redirection (ExternalReference::Redirect in src/codegen/external-reference.cc), which rewrites a C++ function pointer so the simulator can trap it.

The role people remember it playing - “turn a generic call into the right kind of call” - is now played by the call trampolines, and they are hand-written assembly, not CSA. A JS builtin calls back into JS through one of three of them, chosen by what it knows about the receiver:

 c
 
 
// src/builtins/builtins-inl.h:85
constexpr Builtin Builtins::Call(ConvertReceiverMode mode) {
 switch (mode) {
 case ConvertReceiverMode::kNullOrUndefined:
 return Builtin::kCall_ReceiverIsNullOrUndefined;
 case ConvertReceiverMode::kNotNullOrUndefined:
 return Builtin::kCall_ReceiverIsNotNullOrUndefined;
 case ConvertReceiverMode::kAny:
 return Builtin::kCall_ReceiverIsAny;
 }
 UNREACHABLE();
}

and the three are generated by the MacroAssembler, one per architecture:

 cpp
 
 
// src/builtins/builtins-call-gen.cc:45
void Builtins::Generate_Call_ReceiverIsNullOrUndefined(MacroAssembler* masm) {
 Generate_Call(masm, ConvertReceiverMode::kNullOrUndefined);
}

void Builtins::Generate_Call_ReceiverIsNotNullOrUndefined(
 MacroAssembler* masm) {
 Generate_Call(masm, ConvertReceiverMode::kNotNullOrUndefined);
}

void Builtins::Generate_Call_ReceiverIsAny(MacroAssembler* masm) {
 Generate_Call(masm, ConvertReceiverMode::kAny);
}

The split exists because f.call(undefined) and f.call(someObject) have different receiver-conversion rules, and specialising the trampoline on what the caller knows lets the callee skip the check.

Calling back into JavaScript

Call is an extern macro, so it lands on the CSA side:

torque

// src/builtins/base.tq:1646
// Call(Context, Target, Receiver, ...Args)
// TODO(joshualitt): Assuming the context parameter is for throwing when Target
// is non-callable, then we should make it an implicit
// parameter.
extern transitioning macro Call(Context, JSAny, JSAny): JSAny;
extern transitioning macro Call(Context, JSAny, JSAny, JSAny): JSAny;
extern transitioning macro Call(Context, JSAny, JSAny, JSAny, JSAny): JSAny;

The CSA implementation picks the trampoline:

 cpp
 
 
// src/codegen/code-stub-assembler-inl.h:23
template <typename TCallable, class... TArgs>
TNode<JSAny> CodeStubAssembler::Call(TNode<Context> context,
 TNode<TCallable> callable,
 ConvertReceiverMode mode,
 TNode<JSAny> receiver, TArgs... args) {
 static_assert(is_subtype_v<TCallable, Object>);
 static_assert(!is_subtype_v<TCallable, JSFunction>,
 "Use CallFunction() when the callable is a JSFunction.");

 if (IsUndefinedConstant(receiver) || IsNullConstant(receiver)) {
 DCHECK_NE(mode, ConvertReceiverMode::kNotNullOrUndefined);
 return CallJS(Builtins::Call(ConvertReceiverMode::kNullOrUndefined),
 context, callable, receiver, args...);
 }
 DCheckReceiver(mode, receiver);
 return CallJS(Builtins::Call(mode), context, callable, receiver, args...);
}

Two details are worth stopping on. The static_assert refuses to call a JSFunction through the generic Call - you have to use CallFunction, which skips the callable-type dispatch. And the receiver test is a C++ if, evaluated while the graph is being built, not a branch in the emitted code:

 cpp
 
 
// src/compiler/code-assembler.cc:497
bool CodeAssembler::IsUndefinedConstant(TNode<Object> node) {
 compiler::HeapObjectMatcher m(node);
 return m.Is(isolate()->factory()->undefined_value());
}

So if the Torque code hands Call the literal Undefined constant, the kNullOrUndefined trampoline is selected at graph-construction time and the other two never appear in the generated code at all.

transitioning is what makes this legal. Call can run arbitrary JavaScript, which can reallocate the heap and invalidate a FastJSArray witness, so the type system will not let a transient value survive the call.

Tail calls

Torque has a TailCall statement, and it is restricted:

 cpp
 
 
// src/torque/implementation-visitor.cc:2924
 if (is_tailcall) {
 if (Builtin* builtin = Builtin::DynamicCast(CurrentCallable::Get())) {
 const Type* outer_return_type = builtin->signature().return_type;
 if (!return_type->IsSubtypeOf(outer_return_type)) {
 Error("Cannot tailcall, type of result is ", *return_type,
 " but should be a subtype of ", *outer_return_type, ".");
 }
 } else {
 Error("Tail calls are only allowed from builtins");
 }
 }

Two rules, both about keeping the stack honest. A tail call can only happen from a builtin, because a tail call is the builtin - there is no frame to return to, so the callee has to accept the caller’s frame shape. And the result type has to be a subtype of the builtin’s declared return type, so the return value slot is still correct after the jump.

In the backend, a tail call becomes a TailCallBuiltin or a TailCallJSBuiltin - a jump, not a call - which is why a chain of Torque builtins does not grow the stack.

Trade-offs

What Torque buys.

Spec fidelity. The source of Array.prototype.map can be compared line by line with the ECMAScript text, because the step numbers are in the comments.
One calling convention, derived. The parameter count, the parameter names, the machine types and the descriptor all come from one signature. There is no way for the descriptor and the implementation to disagree.
Checked casts. Cast<T>(x) otherwise L lowers to a generated DownCastForTorqueClass<T> that compares the object’s instance type against the class’s FIRST_/LAST_ range and branches to L on failure. The generator even emits the range form rather than integer literals, “because after the metagen cutover the IT values come from tools/metagen/, not from Torque”.
Portable output. The same .tq compiles to x64, arm64 and ia32 code without a line of architecture-specific source.

What Torque costs.

A compiler in the compiler. src/torque/ is roughly 29 000 lines of C++ that have to be maintained, and every V8 contributor has to learn a second language to touch a builtin.
No higher-order macros, no closures. Torque is a control-flow language: there are no lambdas, no first-class functions, and no way to pass a macro as an argument. Some of the uglier Torque in the tree exists purely because the language has no closures.
Everything is compiled twice. The CSA backend and the CC backend (which generates C++ class definitions and debug readers) both have to agree about what a Torque struct means.
A slow migration path. V8 is currently moving builtins from CSA to the Turboshaft assembler, and Torque has a third backend for that. Every new backend is another place for the type system to leak.

The bottom line

Torque is a typed macro language whose only job is to emit calls into another API. It has no arithmetic, no comparison and no loop of its own - just over twenty IR instructions and a type checker. Everything that looks like a language feature (context slots, calling conventions, cast checking, transient-type invalidation) is really a way of making the CSA call underneath it correct by construction.

The mental model to keep: a Torque builtin is a description, and the compiler turns that description into three artefacts - a Code object, a call descriptor, and a JSFunction wrapper - none of which the author wrote by hand.

The thing people get wrong

Torque is not “C++ with nicer syntax”, and it is not a JavaScript dialect. The most common misreading is that transitioning is a documentation annotation - “this function might call back into JS”. It is not: it is a type-system annotation. It is what makes it illegal to hold a FastJSArray across a call that might reallocate the heap, and the compiler enforces that at compile time.

The other common misreading is that a Torque builtin and a Torque macro differ only in syntax. They differ in linking. A macro is inlined into its caller by the Torque compiler and disappears. A builtin becomes a separate Code object with its own descriptor and its own entry in the builtin table, and calling it is a real call with a real argument frame.

For the wider picture of where the generated code ends up, see Code Stub Assembler: How V8 Writes Machine Code by Hand.

Builtins on Opensource internals

Code Stub Assembler: How V8 Writes Machine Code by Hand

The mistake everybody makes first

What CSA adds on top

One source, three architectures

TaggedEqual: the cost of comparing two objects

The helpers that matter

What a CSA builtin looks like

From CSA source to a Code object

Keeping the debugger honest

The inline cache handlers are CSA too

Two different “handler tables”

Trade-offs

The bottom line

The thing people get wrong

Torque: The DSL V8 Uses to Write Its Own Builtins

Why V8 needed a second language

The pipeline, in the order the compiler runs it

The IR: twenty-two instructions, all of them boring on purpose

The keywords that actually matter

A builtin, end to end

How a macro call becomes a CSA call

Context slots: a typed layout

From a builtin to a Code object and a JSFunction

There is no Redirection builtin

Calling back into JavaScript

Tail calls

Trade-offs

The bottom line

The thing people get wrong

There is no `Redirection` builtin