diff --git a/docs/ExtendingLLVM.html b/docs/ExtendingLLVM.html new file mode 100644 index 00000000000..8c880e5ba7c --- /dev/null +++ b/docs/ExtendingLLVM.html @@ -0,0 +1,213 @@ + + + + Extending LLVM: Adding instructions, intrinsics, types, etc. + + + + + +
+ Extending LLVM: Adding instructions, intrinsics, types, etc. +
+ +
    +
  1. Introduction and Warning
    2. +
  2. Adding a new instruction
    3. +
  3. Adding a new intrinsic function
    4. +
  4. Adding a new type +
      +
    1. Adding a new fundamental type
      2. +
    2. Adding a new derived type
      3. +
    5. +
+ +
+

Written by Misha Brukman

+
+ + +
+ Introduction and Warning +
+ + +
+ +

During the course of using LLVM, you may wish to customize it for your +research project or for experimentation. At this point, you may realize that +you need to add something to LLVM, whether it be a new fundamental type, a new +intrinsic function, or a whole new instruction.

+ +

When you come to this realization, stop and think. Do you really need to +extend LLVM? Is it a new fundamental capability that LLVM does not support at +its current incarnation or can it be synthesized from already pre-existing LLVM +elements? If you are not sure, ask on the LLVM-dev list. The +reason is that extending LLVM will get involved as you need to update all the +different passes that you intend to use with your extension, and there are +many LLVM analyses and transformations, so it may be quite a bit of +work.

+ +

Before you invest a significant amount of effort into a non-trivial +extension, ask on the list if what you are +looking to do can be done with already-existing infrastructure, or if maybe +someone else is already working on it. You will save yourself a lot of time and +effort by doing so.

+ +

Finally, these are my notes, and since my extensions are not complete, I may +be missing steps. If you find some omissions, please let me know directly or post on LLVM-dev.

+ +
+ + +
+ Adding a new instruction +
+ + +
+ +

WARNING: adding instructions changes the bytecode +format, and will break compatibility with currently-existing LLVM +installations. Only add an instruction if it is absolutely +necessary.

+ +
    +
  1. llvm/include/llvm/Instruction.def: + add a number for your instruction and an enum name
    2. + +
  2. llvm/include/llvm/i*.h: + add a definition for the class that will represent your instruction
    3. + +
  3. llvm/include/llvm/Support/InstVisitor.h: + add a prototype for a visitor to your new instruction type
    4. + +
  4. llvm/lib/AsmParser/Lexer.l: + add a new token to parse your instruction from assembly text file
    5. + +
  5. llvm/lib/AsmParser/llvmAsmParser.y: + add the grammar on how your instruction can be read and what it will + construct as a result
    6. + +
  6. llvm/lib/Bytecode/Reader/InstructionReader.cpp: + add a case for your instruction and how it will be parsed from bytecode
    7. + +
  7. llvm/lib/VMCore/Instruction.cpp: + add a case for how your instruction will be printed out to assembly
    8. + +
  8. llvm/lib/VMCore/i*.cpp: + implement the class you defined in llvm/include/llvm/i*.h
    9. + +
+ +

Also, you need to implement (or modify) any analyses or passes that you want +to understand this new instruction.

+ +
+ + +
+ Adding a new intrinsic function +
+ + +
+ +

Adding an intrinsic function is easier than adding an instruction, and is +transparent to optimization passes which treat it as an unanalyzable function. +If your added functionality can be expressed as a function call, an intrinsic +function is the method of choice for LLVM extension.

+ +
    + +
  1. llvm/include/llvm/Intrinsics.h: + add an enum in the llvm::Intrinsic namespace
    2. + +
  2. llvm/lib/VMCore/IntrinsicLowering.cpp: + implement the lowering for this intrinsic
    3. + +
  3. llvm/lib/VMCore/Verifier.cpp: + handle the new intrinsic
    4. + +
  4. llvm/lib/VMCore/Function.cpp: + handle the new intrinsic
    5. + +
+ +
+ + +
+ Adding a new type +
+ + +
+ +

WARNING: adding new types changes the bytecode +format, and will break compatibility with currently-existing LLVM +installations. Only add new types if it is absolutely necessary.

+ +
+ + +
+ Adding a fundamental type +
+ +
+ +
    + +
  1. llvm/include/llvm/Type.def: + add enum for the type
    2. + +
  2. llvm/include/llvm/Type.h: + add ID number for the new type; add static Type* for this type
    3. + +
  3. llvm/lib/VMCore/Type.cpp: + add mapping from TypeID => Type*; + initialize the static Type*
    4. + +
  4. llvm/lib/AsmReader/Lexer.l: + add ability to parse in the type from text assembly
    5. + +
  5. llvm/lib/AsmReader/llvmAsmParser.y: + add a token for that type
    6. + +
+ +
+ + +
+ Adding a derived type +
+ +
+ +

TODO

+ +
+ + + +
+
+ Valid CSS! + Valid HTML 4.01! + + Misha Brukman
+ The LLVM Compiler Infrastructure +
+ Last modified: $Date$ +
+ + + diff --git a/docs/llvm.css b/docs/llvm.css index 227b9f94fad..a2b1e0465c3 100644 --- a/docs/llvm.css +++ b/docs/llvm.css @@ -50,3 +50,4 @@ address { clear: right; } .doc_table { text-align: center; width: 90%; padding: 1px 1px 1px 1px; border: 1px; } +.doc_warning { color: red; font-weight: bold }