add-ir-instruction

Adding a New IR Instruction to Hermes

When adding a new IR instruction, you must touch a specific set of files. This skill describes each file, the pattern to follow, and important conventions.

Checklist of Files to Modify

1. doc/IR.md — Documentation (the only place for doc-comments)
2. include/hermes/IR/Instrs.def — Instruction registration
3. include/hermes/IR/Instrs.h — Class definition (NO doc-comments here)
4. include/hermes/IR/IRBuilder.h — Builder declaration
5. lib/IR/IRBuilder.cpp — Builder implementation
6. lib/IR/IRVerifier.cpp — Verification logic
7. lib/Optimizer/Scalar/TypeInference.cpp — Type inference stub
8. lib/BCGen/HBC/ISel.cpp — HBC instruction selection (stub or implementation)
9. lib/BCGen/SH/SH.cpp — Static Hermes codegen (stub or implementation)
10. lib/BCGen/facebook/Mins/Mins.cpp — Mins codegen (stub or implementation)
11. Tests — At minimum, update or add tests in test/

If the instruction needs lowering (i.e., it does not map directly to a bytecode opcode), you also need:

12. include/hermes/BCGen/Lowering.h — Lowering pass declaration
13. lib/BCGen/Lowering.cpp — Lowering pass implementation
14. lib/BCGen/HBC/LoweringPipelines.cpp — Register pass in HBC pipeline
15. lib/BCGen/SH/SH.cpp (in lowerModuleIR) — Register pass in SH pipeline

Step-by-Step Guide

1. Document in doc/IR.md

This is the ONLY place to put documentation for the instruction. Do NOT add doc-comments to Instrs.h.

Add a markdown table entry in the appropriate section:

### MyNewInst
 
MyNewInst | _
--- | --- |
Description | Brief description of what the instruction does.
Example |   `MyNewInst %arg1, %arg2 : type`
Arguments | *%arg1* is ... *%arg2* is ...
Semantics | Describe the semantics, referencing the spec where appropriate.
Effects | Describe side effects (e.g., "May read and write memory.", "May read memory and throw.", "Does not read or write memory.").

2. Register in Instrs.def

Add a DEF_VALUE entry. Place it near related instructions:

If it's a subclass of another instruction, use the parent as the second argument. If it's a terminator, use TERMINATOR instead of DEF_VALUE.

3. Define the class in Instrs.h

Do NOT add doc-comments to this file. Documentation belongs in doc/IR.md.

Follow this exact pattern:

4. Add IRBuilder declaration in IRBuilder.h

5. Add IRBuilder implementation in IRBuilder.cpp

6. Add verification in IRVerifier.cpp

Add a visit method that checks invariants:

7. Add type inference in TypeInference.cpp

Add an infer method. For instructions without output, return createNoType():

8. Add code generation stubs

If the instruction is lowered before codegen, add fatal stubs. Otherwise, implement the actual code generation.

HBC ISel (lib/BCGen/HBC/ISel.cpp):

SH (lib/BCGen/SH/SH.cpp):

Mins (lib/BCGen/facebook/Mins/Mins.cpp): Unless asked to, do not implement Mins codegen for new instructions. Leave it as a stub.

9. (If needed) Add a lowering pass

Declare in Lowering.h:

Implement in Lowering.cpp:

Register in pipelines:

In lib/BCGen/HBC/LoweringPipelines.cpp and in lib/BCGen/SH/SH.cpp (lowerModuleIR), add PM.addPass(createLowerMyNewInst()); at the appropriate point (before any pass that would need to process instructions introduced by the lowering).

10. Add or update tests

Add lit tests in the appropriate test/ subdirectory. Use %FileCheck or %FileCheckOrRegen to verify the IR output. If existing tests cover the feature, update their expected output to reflect the new instruction.

Which subdirectory to use depends on how the instruction interacts with the compiler pipeline — not every instruction needs tests in every directory:

• test/IRGen/ — When the instruction is generated directly from JavaScript source. Tests here verify that IRGen produces the expected IR.
• test/Optimizer/ — When the instruction affects or interacts with optimization passes.
• test/BCGen/ — Not used as often, but if this IR instruction is used in combination with new bytecode instructions, then place bytecode gen tests here.

Key Conventions

• No doc-comments in Instrs.h. All documentation goes in doc/IR.md. The class in Instrs.h should have no /// or /** */ comments describing what the instruction does. Brief inline comments explaining non-obvious implementation details (like side effects) are fine.
• Placement matters. Place the new instruction near related instructions in every file (e.g., private field instructions are grouped together).
• Consistent naming. The instruction name (e.g., FooBarInst) must be consistent across all files: Instrs.def, Instrs.h, IRBuilder.h/cpp, IRVerifier.cpp, TypeInference.cpp, and all codegen files.
• The ValueKind is derived automatically. When you add DEF_VALUE(MyNewInst, Instruction) to Instrs.def, the enum value ValueKind::MyNewInstKind is generated automatically.**