Disable this peephole for now. We can't keep track of the fact that the immediate...
[oota-llvm.git] / lib / Target / X86 / README.txt
1 //===- README.txt - Information about the X86 backend and related files ---===//
2 //
3 // This file contains random notes and points of interest about the X86 backend.
4 //
5 //===----------------------------------------------------------------------===//
6
7 ===========
8 I. Overview
9 ===========
10
11 This directory contains a machine description for the X86 processor.  Currently
12 this machine description is used for a high performance code generator used by a
13 LLVM JIT.  One of the main objectives that we would like to support with this
14 project is to build a nice clean code generator that may be extended in the
15 future in a variety of ways: new targets, new optimizations, new
16 transformations, etc.
17
18 This document describes the current state of the LLVM JIT, along with
19 implementation notes, design decisions, and other stuff.
20
21
22 ===================================
23 II. Architecture / Design Decisions
24 ===================================
25
26 We designed the infrastructure into the generic LLVM machine specific
27 representation, which allows us to support as many targets as possible with our
28 framework.  This framework should allow us to share many common machine specific
29 transformations (register allocation, instruction scheduling, etc...) among all
30 of the backends that may eventually be supported by LLVM, and ensures that the
31 JIT and static compiler backends are largely shared.
32
33 At the high-level, LLVM code is translated to a machine specific representation
34 formed out of MachineFunction, MachineBasicBlock, and MachineInstr instances
35 (defined in include/llvm/CodeGen).  This representation is completely target
36 agnostic, representing instructions in their most abstract form: an opcode, a
37 destination, and a series of operands.  This representation is designed to
38 support both SSA representation for machine code, as well as a register
39 allocated, non-SSA form.
40
41 Because the Machine* representation must work regardless of the target machine,
42 it contains very little semantic information about the program.  To get semantic
43 information about the program, a layer of Target description datastructures are
44 used, defined in include/llvm/Target.
45
46 Note that there is some amount of complexity that the X86 backend contains due
47 to the Sparc backend's legacy requirements.  These should eventually fade away
48 as the project progresses.
49
50
51 SSA Instruction Representation
52 ------------------------------
53 Target machine instructions are represented as instances of MachineInstr, and
54 all specific machine instruction types should have an entry in the
55 InstructionInfo table defined through X86InstrInfo.def.  In the X86 backend,
56 there are two particularly interesting forms of machine instruction: those that
57 produce a value (such as add), and those that do not (such as a store).
58
59 Instructions that produce a value use Operand #0 as the "destination" register.
60 When printing the assembly code with the built-in machine instruction printer,
61 these destination registers will be printed to the left side of an '=' sign, as
62 in: %reg1027 = addl %reg1026, %reg1025
63
64 This 'addl' MachineInstruction contains three "operands": the first is the
65 destination register (#1027), the second is the first source register (#1026)
66 and the third is the second source register (#1025).  Never forget the
67 destination register will show up in the MachineInstr operands vector.  The code
68 to generate this instruction looks like this:
69
70   BuildMI(BB, X86::ADDrr32, 2, 1027).addReg(1026).addReg(1025);
71
72 The first argument to BuildMI is the basic block to append the machine
73 instruction to, the second is the opcode, the third is the number of operands,
74 the fourth is the destination register.  The two addReg calls specify operands
75 in order.
76
77 MachineInstrs that do not produce a value do not have this implicit first
78 operand, they simply have #operands = #uses.  To create them, simply do not
79 specify a destination register to the BuildMI call.
80
81
82 ======================
83 IV. Source Code Layout
84 ======================
85
86 The LLVM-JIT is composed of source files primarily in the following locations:
87
88 include/llvm/CodeGen
89 --------------------
90 This directory contains header files that are used to represent the program in a
91 machine specific representation.  It currently also contains a bunch of stuff
92 used by the Sparc backend that we don't want to get mixed up in, such as
93 register allocation internals.
94
95 include/llvm/Target
96 -------------------
97 This directory contains header files that are used to interpret the machine
98 specific representation of the program.  This allows us to write generic
99 transformations that will work on any target that implements the interfaces
100 defined in this directory.  The only classes used by the X86 backend so far are
101 the TargetMachine, TargetData, MachineInstrInfo, and MRegisterInfo classes.
102
103 lib/CodeGen
104 -----------
105 This directory will contain all of the target independent transformations (for
106 example, register allocation) that we write.  These transformations should only
107 use information exposed through the Target interface, they should not include
108 any target specific header files.
109
110 lib/Target/X86
111 --------------
112 This directory contains the machine description for X86 that is required to the
113 rest of the compiler working.  It contains any code that is truly specific to
114 the X86 backend, for example the instruction selector and machine code emitter.
115
116 tools/lli/JIT
117 -------------
118 This directory contains the top-level code for the JIT compiler.  This code
119 basically boils down to a call to TargetMachine::addPassesToJITCompile.  As we
120 progress with the project, this will also contain the compile-dispatch-recompile
121 loop.
122
123 test/Regression/Jello
124 ---------------------
125 This directory contains regression tests for the JIT.
126
127
128 ==================================================
129 V. Strange Things, or, Things That Should Be Known
130 ==================================================
131
132 Representing memory in MachineInstrs
133 ------------------------------------
134
135 The x86 has a very, uhm, flexible, way of accessing memory.  It is capable of
136 addressing memory addresses of the following form directly in integer
137 instructions (which use ModR/M addressing):
138
139    Base+[1,2,4,8]*IndexReg+Disp32
140
141 Wow, that's crazy.  In order to represent this, LLVM tracks no less that 4
142 operands for each memory operand of this form.  This means that the "load" form
143 of 'mov' has the following "Operands" in this order:
144
145 Index:        0     |    1        2       3           4
146 Meaning:   DestReg, | BaseReg,  Scale, IndexReg, Displacement
147 OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg,   SignExtImm
148
149 Stores and all other instructions treat the four memory operands in the same
150 way, in the same order.
151
152
153 ==========================
154 VI. TODO / Future Projects
155 ==========================
156
157 There are a large number of things remaining to do.  Here is a partial list:
158
159 Next Phase:
160 -----------
161 1. Implement linear time optimal instruction selector
162 2. Implement smarter (linear scan?) register allocator
163
164 After this project:
165 -------------------
166 1. Implement lots of nifty runtime optimizations
167 2. Implement new targets: IA64? X86-64? M68k? MMIX?  Who knows...
168
169 Infrastructure Improvements:
170 ----------------------------
171
172 1. Bytecode is designed to be able to read particular functions from the
173    bytecode without having to read the whole program.  Bytecode reader should be
174    extended to allow on-demand loading of functions.
175
176 2. X86/Printer.cpp and Sparc/EmitAssembly.cpp both have copies of what is
177    roughly the same code, used to output constants in a form the assembler
178    can understand. These functions should be shared at some point. They
179    should be rewritten to pass around iostreams instead of strings. The
180    list of functions is as follows:
181
182    isStringCompatible
183    toOctal
184    ConstantExprToString
185    valToExprString
186    getAsCString
187    printSingleConstantValue (with TypeToDataDirective inlined)
188    printConstantValueOnly