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:

1. include/hermes/BCGen/Lowering.h — Lowering pass declaration
2. lib/BCGen/Lowering.cpp — Lowering pass implementation
3. lib/BCGen/HBC/LoweringPipelines.cpp — Register pass in HBC pipeline
4. 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:

DEF_VALUE(MyNewInst, Instruction)

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:

class MyNewInst : public Instruction {
  MyNewInst(const MyNewInst &) = delete;
  void operator=(const MyNewInst &) = delete;

 public:
  enum { Arg1Idx, Arg2Idx };
  explicit MyNewInst(Value *arg1, Value *arg2)
      : Instruction(ValueKind::MyNewInstKind) {
    // Optional assertions on operand types:
    // assert(arg2->getType().isSomeType() && "message");

    // Set the result type:
    setType(Type::createNoType());  // for instructions with no output
    // or: setType(Type::createFoo()); for typed instructions

    pushOperand(arg1);
    pushOperand(arg2);
  }

  explicit MyNewInst(
      const MyNewInst *src,
      llvh::ArrayRef<Value *> operands)
      : Instruction(src, operands) {}

  Value *getArg1() const {
    return getOperand(Arg1Idx);
  }
  Value *getArg2() const {
    return getOperand(Arg2Idx);
  }

  static bool hasOutput() {
    return false;  // true if the instruction produces a value
  }
  static bool isTyped() {
    return false;  // true if the output type is meaningful
  }

  SideEffect getSideEffectImpl() const {
    // Compose side effects. Common patterns:
    //   return {};                                          // pure
    //   return SideEffect{}.setReadHeap();                  // reads memory
    //   return SideEffect{}.setReadHeap().setWriteHeap();   // reads+writes
    //   return SideEffect{}.setThrow().setReadHeap();       // may throw + read
    return SideEffect{}.setThrow().setReadHeap();
  }

  static bool classof(const Value *V) {
    ValueKind kind = V->getKind();
    return kind == ValueKind::MyNewInstKind;
  }

…