docs/codegen/code-stub-assembler.md - v8/v8.git - Git at Google

 # CodeStubAssembler (CSA) in V8

 The `CodeStubAssembler` (CSA) is a critical component in V8's code generation pipeline. It provides a JavaScript-specific "macro-assembler" interface on top of V8's low-level `compiler::CodeAssembler`.

 ## Overview

 CSA is used to write low-level code, such as builtins (e.g., `Promise` implementation details, parts of `Array.prototype` methods) and bytecode handlers for Ignition. While many builtins are now written in **Torque** (which generates CSA code), understanding CSA is still essential for working on V8's low-level components. It allows writing code in a way that is portable across all architectures supported by V8 (x64, ARM, ARM64, MIPS, etc.) without having to write raw machine code for each platform.


 ## How it Provides a Portable Interface

 ### 1. Instruction Fallbacks
 For many complex operations (e.g., `Float64Ceil`, `Float64Floor`, `PopulationCount`), CSA checks if the target architecture supports native instructions for these operations (e.g., via `IsFloat64RoundUpSupported()`).
 *   **If supported**: It generates the specific machine instruction directly.
 *   **If not supported**: It provides a software fallback implementation in C++ that generates a sequence of simpler operations to achieve the same result.
 This ensures that the same CSA code can run on all platforms, regardless of their hardware capabilities.

 ### 2. Abstraction of Data Representation
 CSA abstracts away platform-specific details like pointer size, pointer compression, and `Smi` (Small Integer) representation.
 *   For example, arithmetic operations on Smis (like `SmiAdd`) automatically handle whether Smis are 31-bit or 32-bit and whether they need to be shifted or masked, based on the build configuration.

 ### 3. Type Safety with TNodes
 While it feels like assembly, it is strongly typed at the C++ level using `TNode<T>` (e.g., `TNode<Smi>`, `TNode<IntPtrT>`, `TNode<Context>`). This prevents many common low-level errors by ensuring that operations are only performed on compatible types at compile time.

 ### 4. High-Level Abstractions
 CSA provides higher-level operations that are common in JavaScript execution but would be tedious to write in raw assembly:
 *   Allocating objects in the heap (`AllocateInNewSpace`).
 *   Checking object types and map transitions.
 *   Calling JavaScript functions and other builtins.
 ## Torque and CSA

 V8 now uses a domain-specific language called **Torque** for writing many of its builtins. Torque code (files with `.tq` extension) is compiled by the Torque compiler into C++ code that uses the `CodeStubAssembler` interface.
 *   **Torque** provides a higher-level, more readable syntax with strong typing.
 *   **CSA** is the underlying implementation layer that Torque generates.

 For more details on Torque, see the [Torque documentation](../torque.md).

 ## File Structure
 *   `src/codegen/code-stub-assembler.h`: Header file defining the CSA interface.
 *   `src/codegen/code-stub-assembler.cc`: Implementation of the CSA operations.
	# CodeStubAssembler (CSA) in V8

	The `CodeStubAssembler` (CSA) is a critical component in V8's code generation pipeline. It provides a JavaScript-specific "macro-assembler" interface on top of V8's low-level `compiler::CodeAssembler`.

	## Overview

	CSA is used to write low-level code, such as builtins (e.g., `Promise` implementation details, parts of `Array.prototype` methods) and bytecode handlers for Ignition. While many builtins are now written in Torque (which generates CSA code), understanding CSA is still essential for working on V8's low-level components. It allows writing code in a way that is portable across all architectures supported by V8 (x64, ARM, ARM64, MIPS, etc.) without having to write raw machine code for each platform.


	## How it Provides a Portable Interface

	### 1. Instruction Fallbacks
	For many complex operations (e.g., `Float64Ceil`, `Float64Floor`, `PopulationCount`), CSA checks if the target architecture supports native instructions for these operations (e.g., via `IsFloat64RoundUpSupported()`).
	* If supported: It generates the specific machine instruction directly.
	* If not supported: It provides a software fallback implementation in C++ that generates a sequence of simpler operations to achieve the same result.
	This ensures that the same CSA code can run on all platforms, regardless of their hardware capabilities.

	### 2. Abstraction of Data Representation
	CSA abstracts away platform-specific details like pointer size, pointer compression, and `Smi` (Small Integer) representation.
	* For example, arithmetic operations on Smis (like `SmiAdd`) automatically handle whether Smis are 31-bit or 32-bit and whether they need to be shifted or masked, based on the build configuration.

	### 3. Type Safety with TNodes
	While it feels like assembly, it is strongly typed at the C++ level using `TNode<T>` (e.g., `TNode<Smi>`, `TNode<IntPtrT>`, `TNode<Context>`). This prevents many common low-level errors by ensuring that operations are only performed on compatible types at compile time.

	### 4. High-Level Abstractions
	CSA provides higher-level operations that are common in JavaScript execution but would be tedious to write in raw assembly:
	* Allocating objects in the heap (`AllocateInNewSpace`).
	* Checking object types and map transitions.
	* Calling JavaScript functions and other builtins.
	## Torque and CSA

	V8 now uses a domain-specific language called Torque for writing many of its builtins. Torque code (files with `.tq` extension) is compiled by the Torque compiler into C++ code that uses the `CodeStubAssembler` interface.
	* Torque provides a higher-level, more readable syntax with strong typing.
	* CSA is the underlying implementation layer that Torque generates.

	For more details on Torque, see the [Torque documentation](../torque.md).

	## File Structure
	* `src/codegen/code-stub-assembler.h`: Header file defining the CSA interface.
	* `src/codegen/code-stub-assembler.cc`: Implementation of the CSA operations.