linux-user: Use safe_syscall for execve syscall
[qemu.git] / tcg / README
1 Tiny Code Generator - Fabrice Bellard.
2
3 1) Introduction
4
5 TCG (Tiny Code Generator) began as a generic backend for a C
6 compiler. It was simplified to be used in QEMU. It also has its roots
7 in the QOP code generator written by Paul Brook. 
8
9 2) Definitions
10
11 The TCG "target" is the architecture for which we generate the
12 code. It is of course not the same as the "target" of QEMU which is
13 the emulated architecture. As TCG started as a generic C backend used
14 for cross compiling, it is assumed that the TCG target is different
15 from the host, although it is never the case for QEMU.
16
17 In this document, we use "guest" to specify what architecture we are
18 emulating; "target" always means the TCG target, the machine on which
19 we are running QEMU.
20
21 A TCG "function" corresponds to a QEMU Translated Block (TB).
22
23 A TCG "temporary" is a variable only live in a basic
24 block. Temporaries are allocated explicitly in each function.
25
26 A TCG "local temporary" is a variable only live in a function. Local
27 temporaries are allocated explicitly in each function.
28
29 A TCG "global" is a variable which is live in all the functions
30 (equivalent of a C global variable). They are defined before the
31 functions defined. A TCG global can be a memory location (e.g. a QEMU
32 CPU register), a fixed host register (e.g. the QEMU CPU state pointer)
33 or a memory location which is stored in a register outside QEMU TBs
34 (not implemented yet).
35
36 A TCG "basic block" corresponds to a list of instructions terminated
37 by a branch instruction. 
38
39 An operation with "undefined behavior" may result in a crash.
40
41 An operation with "unspecified behavior" shall not crash.  However,
42 the result may be one of several possibilities so may be considered
43 an "undefined result".
44
45 3) Intermediate representation
46
47 3.1) Introduction
48
49 TCG instructions operate on variables which are temporaries, local
50 temporaries or globals. TCG instructions and variables are strongly
51 typed. Two types are supported: 32 bit integers and 64 bit
52 integers. Pointers are defined as an alias to 32 bit or 64 bit
53 integers depending on the TCG target word size.
54
55 Each instruction has a fixed number of output variable operands, input
56 variable operands and always constant operands.
57
58 The notable exception is the call instruction which has a variable
59 number of outputs and inputs.
60
61 In the textual form, output operands usually come first, followed by
62 input operands, followed by constant operands. The output type is
63 included in the instruction name. Constants are prefixed with a '$'.
64
65 add_i32 t0, t1, t2  (t0 <- t1 + t2)
66
67 3.2) Assumptions
68
69 * Basic blocks
70
71 - Basic blocks end after branches (e.g. brcond_i32 instruction),
72   goto_tb and exit_tb instructions.
73 - Basic blocks start after the end of a previous basic block, or at a
74   set_label instruction.
75
76 After the end of a basic block, the content of temporaries is
77 destroyed, but local temporaries and globals are preserved.
78
79 * Floating point types are not supported yet
80
81 * Pointers: depending on the TCG target, pointer size is 32 bit or 64
82   bit. The type TCG_TYPE_PTR is an alias to TCG_TYPE_I32 or
83   TCG_TYPE_I64.
84
85 * Helpers:
86
87 Using the tcg_gen_helper_x_y it is possible to call any function
88 taking i32, i64 or pointer types. By default, before calling a helper,
89 all globals are stored at their canonical location and it is assumed
90 that the function can modify them. By default, the helper is allowed to
91 modify the CPU state or raise an exception.
92
93 This can be overridden using the following function modifiers:
94 - TCG_CALL_NO_READ_GLOBALS means that the helper does not read globals,
95   either directly or via an exception. They will not be saved to their
96   canonical locations before calling the helper.
97 - TCG_CALL_NO_WRITE_GLOBALS means that the helper does not modify any globals.
98   They will only be saved to their canonical location before calling helpers,
99   but they won't be reloaded afterwise.
100 - TCG_CALL_NO_SIDE_EFFECTS means that the call to the function is removed if
101   the return value is not used.
102
103 Note that TCG_CALL_NO_READ_GLOBALS implies TCG_CALL_NO_WRITE_GLOBALS.
104
105 On some TCG targets (e.g. x86), several calling conventions are
106 supported.
107
108 * Branches:
109
110 Use the instruction 'br' to jump to a label.
111
112 3.3) Code Optimizations
113
114 When generating instructions, you can count on at least the following
115 optimizations:
116
117 - Single instructions are simplified, e.g.
118
119    and_i32 t0, t0, $0xffffffff
120     
121   is suppressed.
122
123 - A liveness analysis is done at the basic block level. The
124   information is used to suppress moves from a dead variable to
125   another one. It is also used to remove instructions which compute
126   dead results. The later is especially useful for condition code
127   optimization in QEMU.
128
129   In the following example:
130
131   add_i32 t0, t1, t2
132   add_i32 t0, t0, $1
133   mov_i32 t0, $1
134
135   only the last instruction is kept.
136
137 3.4) Instruction Reference
138
139 ********* Function call
140
141 * call <ret> <params> ptr
142
143 call function 'ptr' (pointer type)
144
145 <ret> optional 32 bit or 64 bit return value
146 <params> optional 32 bit or 64 bit parameters
147
148 ********* Jumps/Labels
149
150 * set_label $label
151
152 Define label 'label' at the current program point.
153
154 * br $label
155
156 Jump to label.
157
158 * brcond_i32/i64 t0, t1, cond, label
159
160 Conditional jump if t0 cond t1 is true. cond can be:
161     TCG_COND_EQ
162     TCG_COND_NE
163     TCG_COND_LT /* signed */
164     TCG_COND_GE /* signed */
165     TCG_COND_LE /* signed */
166     TCG_COND_GT /* signed */
167     TCG_COND_LTU /* unsigned */
168     TCG_COND_GEU /* unsigned */
169     TCG_COND_LEU /* unsigned */
170     TCG_COND_GTU /* unsigned */
171
172 ********* Arithmetic
173
174 * add_i32/i64 t0, t1, t2
175
176 t0=t1+t2
177
178 * sub_i32/i64 t0, t1, t2
179
180 t0=t1-t2
181
182 * neg_i32/i64 t0, t1
183
184 t0=-t1 (two's complement)
185
186 * mul_i32/i64 t0, t1, t2
187
188 t0=t1*t2
189
190 * div_i32/i64 t0, t1, t2
191
192 t0=t1/t2 (signed). Undefined behavior if division by zero or overflow.
193
194 * divu_i32/i64 t0, t1, t2
195
196 t0=t1/t2 (unsigned). Undefined behavior if division by zero.
197
198 * rem_i32/i64 t0, t1, t2
199
200 t0=t1%t2 (signed). Undefined behavior if division by zero or overflow.
201
202 * remu_i32/i64 t0, t1, t2
203
204 t0=t1%t2 (unsigned). Undefined behavior if division by zero.
205
206 ********* Logical
207
208 * and_i32/i64 t0, t1, t2
209
210 t0=t1&t2
211
212 * or_i32/i64 t0, t1, t2
213
214 t0=t1|t2
215
216 * xor_i32/i64 t0, t1, t2
217
218 t0=t1^t2
219
220 * not_i32/i64 t0, t1
221
222 t0=~t1
223
224 * andc_i32/i64 t0, t1, t2
225
226 t0=t1&~t2
227
228 * eqv_i32/i64 t0, t1, t2
229
230 t0=~(t1^t2), or equivalently, t0=t1^~t2
231
232 * nand_i32/i64 t0, t1, t2
233
234 t0=~(t1&t2)
235
236 * nor_i32/i64 t0, t1, t2
237
238 t0=~(t1|t2)
239
240 * orc_i32/i64 t0, t1, t2
241
242 t0=t1|~t2
243
244 ********* Shifts/Rotates
245
246 * shl_i32/i64 t0, t1, t2
247
248 t0=t1 << t2. Unspecified behavior if t2 < 0 or t2 >= 32 (resp 64)
249
250 * shr_i32/i64 t0, t1, t2
251
252 t0=t1 >> t2 (unsigned). Unspecified behavior if t2 < 0 or t2 >= 32 (resp 64)
253
254 * sar_i32/i64 t0, t1, t2
255
256 t0=t1 >> t2 (signed). Unspecified behavior if t2 < 0 or t2 >= 32 (resp 64)
257
258 * rotl_i32/i64 t0, t1, t2
259
260 Rotation of t2 bits to the left.
261 Unspecified behavior if t2 < 0 or t2 >= 32 (resp 64)
262
263 * rotr_i32/i64 t0, t1, t2
264
265 Rotation of t2 bits to the right.
266 Unspecified behavior if t2 < 0 or t2 >= 32 (resp 64)
267
268 ********* Misc
269
270 * mov_i32/i64 t0, t1
271
272 t0 = t1
273
274 Move t1 to t0 (both operands must have the same type).
275
276 * ext8s_i32/i64 t0, t1
277 ext8u_i32/i64 t0, t1
278 ext16s_i32/i64 t0, t1
279 ext16u_i32/i64 t0, t1
280 ext32s_i64 t0, t1
281 ext32u_i64 t0, t1
282
283 8, 16 or 32 bit sign/zero extension (both operands must have the same type)
284
285 * bswap16_i32/i64 t0, t1
286
287 16 bit byte swap on a 32/64 bit value. It assumes that the two/six high order
288 bytes are set to zero.
289
290 * bswap32_i32/i64 t0, t1
291
292 32 bit byte swap on a 32/64 bit value. With a 64 bit value, it assumes that
293 the four high order bytes are set to zero.
294
295 * bswap64_i64 t0, t1
296
297 64 bit byte swap
298
299 * discard_i32/i64 t0
300
301 Indicate that the value of t0 won't be used later. It is useful to
302 force dead code elimination.
303
304 * deposit_i32/i64 dest, t1, t2, pos, len
305
306 Deposit T2 as a bitfield into T1, placing the result in DEST.
307 The bitfield is described by POS/LEN, which are immediate values:
308
309   LEN - the length of the bitfield
310   POS - the position of the first bit, counting from the LSB
311
312 For example, pos=8, len=4 indicates a 4-bit field at bit 8.
313 This operation would be equivalent to
314
315   dest = (t1 & ~0x0f00) | ((t2 << 8) & 0x0f00)
316
317 * extrl_i64_i32 t0, t1
318
319 For 64-bit hosts only, extract the low 32-bits of input T1 and place it
320 into 32-bit output T0.  Depending on the host, this may be a simple move,
321 or may require additional canonicalization.
322
323 * extrh_i64_i32 t0, t1
324
325 For 64-bit hosts only, extract the high 32-bits of input T1 and place it
326 into 32-bit output T0.  Depending on the host, this may be a simple shift,
327 or may require additional canonicalization.
328
329 ********* Conditional moves
330
331 * setcond_i32/i64 dest, t1, t2, cond
332
333 dest = (t1 cond t2)
334
335 Set DEST to 1 if (T1 cond T2) is true, otherwise set to 0.
336
337 * movcond_i32/i64 dest, c1, c2, v1, v2, cond
338
339 dest = (c1 cond c2 ? v1 : v2)
340
341 Set DEST to V1 if (C1 cond C2) is true, otherwise set to V2.
342
343 ********* Type conversions
344
345 * ext_i32_i64 t0, t1
346 Convert t1 (32 bit) to t0 (64 bit) and does sign extension
347
348 * extu_i32_i64 t0, t1
349 Convert t1 (32 bit) to t0 (64 bit) and does zero extension
350
351 * trunc_i64_i32 t0, t1
352 Truncate t1 (64 bit) to t0 (32 bit)
353
354 * concat_i32_i64 t0, t1, t2
355 Construct t0 (64-bit) taking the low half from t1 (32 bit) and the high half
356 from t2 (32 bit).
357
358 * concat32_i64 t0, t1, t2
359 Construct t0 (64-bit) taking the low half from t1 (64 bit) and the high half
360 from t2 (64 bit).
361
362 ********* Load/Store
363
364 * ld_i32/i64 t0, t1, offset
365 ld8s_i32/i64 t0, t1, offset
366 ld8u_i32/i64 t0, t1, offset
367 ld16s_i32/i64 t0, t1, offset
368 ld16u_i32/i64 t0, t1, offset
369 ld32s_i64 t0, t1, offset
370 ld32u_i64 t0, t1, offset
371
372 t0 = read(t1 + offset)
373 Load 8, 16, 32 or 64 bits with or without sign extension from host memory. 
374 offset must be a constant.
375
376 * st_i32/i64 t0, t1, offset
377 st8_i32/i64 t0, t1, offset
378 st16_i32/i64 t0, t1, offset
379 st32_i64 t0, t1, offset
380
381 write(t0, t1 + offset)
382 Write 8, 16, 32 or 64 bits to host memory.
383
384 All this opcodes assume that the pointed host memory doesn't correspond
385 to a global. In the latter case the behaviour is unpredictable.
386
387 ********* Multiword arithmetic support
388
389 * add2_i32/i64 t0_low, t0_high, t1_low, t1_high, t2_low, t2_high
390 * sub2_i32/i64 t0_low, t0_high, t1_low, t1_high, t2_low, t2_high
391
392 Similar to add/sub, except that the double-word inputs T1 and T2 are
393 formed from two single-word arguments, and the double-word output T0
394 is returned in two single-word outputs.
395
396 * mulu2_i32/i64 t0_low, t0_high, t1, t2
397
398 Similar to mul, except two unsigned inputs T1 and T2 yielding the full
399 double-word product T0.  The later is returned in two single-word outputs.
400
401 * muls2_i32/i64 t0_low, t0_high, t1, t2
402
403 Similar to mulu2, except the two inputs T1 and T2 are signed.
404
405 ********* 64-bit guest on 32-bit host support
406
407 The following opcodes are internal to TCG.  Thus they are to be implemented by
408 32-bit host code generators, but are not to be emitted by guest translators.
409 They are emitted as needed by inline functions within "tcg-op.h".
410
411 * brcond2_i32 t0_low, t0_high, t1_low, t1_high, cond, label
412
413 Similar to brcond, except that the 64-bit values T0 and T1
414 are formed from two 32-bit arguments.
415
416 * setcond2_i32 dest, t1_low, t1_high, t2_low, t2_high, cond
417
418 Similar to setcond, except that the 64-bit values T1 and T2 are
419 formed from two 32-bit arguments.  The result is a 32-bit value.
420
421 ********* QEMU specific operations
422
423 * exit_tb t0
424
425 Exit the current TB and return the value t0 (word type).
426
427 * goto_tb index
428
429 Exit the current TB and jump to the TB index 'index' (constant) if the
430 current TB was linked to this TB. Otherwise execute the next
431 instructions. Only indices 0 and 1 are valid and tcg_gen_goto_tb may be issued
432 at most once with each slot index per TB.
433
434 * qemu_ld_i32/i64 t0, t1, flags, memidx
435 * qemu_st_i32/i64 t0, t1, flags, memidx
436
437 Load data at the guest address t1 into t0, or store data in t0 at guest
438 address t1.  The _i32/_i64 size applies to the size of the input/output
439 register t0 only.  The address t1 is always sized according to the guest,
440 and the width of the memory operation is controlled by flags.
441
442 Both t0 and t1 may be split into little-endian ordered pairs of registers
443 if dealing with 64-bit quantities on a 32-bit host.
444
445 The memidx selects the qemu tlb index to use (e.g. user or kernel access).
446 The flags are the TCGMemOp bits, selecting the sign, width, and endianness
447 of the memory access.
448
449 For a 32-bit host, qemu_ld/st_i64 is guaranteed to only be used with a
450 64-bit memory access specified in flags.
451
452 *********
453
454 Note 1: Some shortcuts are defined when the last operand is known to be
455 a constant (e.g. addi for add, movi for mov).
456
457 Note 2: When using TCG, the opcodes must never be generated directly
458 as some of them may not be available as "real" opcodes. Always use the
459 function tcg_gen_xxx(args).
460
461 4) Backend
462
463 tcg-target.h contains the target specific definitions. tcg-target.inc.c
464 contains the target specific code; it is #included by tcg/tcg.c, rather
465 than being a standalone C file.
466
467 4.1) Assumptions
468
469 The target word size (TCG_TARGET_REG_BITS) is expected to be 32 bit or
470 64 bit. It is expected that the pointer has the same size as the word.
471
472 On a 32 bit target, all 64 bit operations are converted to 32 bits. A
473 few specific operations must be implemented to allow it (see add2_i32,
474 sub2_i32, brcond2_i32).
475
476 On a 64 bit target, the values are transferred between 32 and 64-bit
477 registers using the following ops:
478 - trunc_shr_i64_i32
479 - ext_i32_i64
480 - extu_i32_i64
481
482 They ensure that the values are correctly truncated or extended when
483 moved from a 32-bit to a 64-bit register or vice-versa. Note that the
484 trunc_shr_i64_i32 is an optional op. It is not necessary to implement
485 it if all the following conditions are met:
486 - 64-bit registers can hold 32-bit values
487 - 32-bit values in a 64-bit register do not need to stay zero or
488   sign extended
489 - all 32-bit TCG ops ignore the high part of 64-bit registers
490
491 Floating point operations are not supported in this version. A
492 previous incarnation of the code generator had full support of them,
493 but it is better to concentrate on integer operations first.
494
495 4.2) Constraints
496
497 GCC like constraints are used to define the constraints of every
498 instruction. Memory constraints are not supported in this
499 version. Aliases are specified in the input operands as for GCC.
500
501 The same register may be used for both an input and an output, even when
502 they are not explicitly aliased.  If an op expands to multiple target
503 instructions then care must be taken to avoid clobbering input values.
504 GCC style "early clobber" outputs are not currently supported.
505
506 A target can define specific register or constant constraints. If an
507 operation uses a constant input constraint which does not allow all
508 constants, it must also accept registers in order to have a fallback.
509
510 The movi_i32 and movi_i64 operations must accept any constants.
511
512 The mov_i32 and mov_i64 operations must accept any registers of the
513 same type.
514
515 The ld/st instructions must accept signed 32 bit constant offsets. It
516 can be implemented by reserving a specific register to compute the
517 address if the offset is too big.
518
519 The ld/st instructions must accept any destination (ld) or source (st)
520 register.
521
522 4.3) Function call assumptions
523
524 - The only supported types for parameters and return value are: 32 and
525   64 bit integers and pointer.
526 - The stack grows downwards.
527 - The first N parameters are passed in registers.
528 - The next parameters are passed on the stack by storing them as words.
529 - Some registers are clobbered during the call. 
530 - The function can return 0 or 1 value in registers. On a 32 bit
531   target, functions must be able to return 2 values in registers for
532   64 bit return type.
533
534 5) Recommended coding rules for best performance
535
536 - Use globals to represent the parts of the QEMU CPU state which are
537   often modified, e.g. the integer registers and the condition
538   codes. TCG will be able to use host registers to store them.
539
540 - Avoid globals stored in fixed registers. They must be used only to
541   store the pointer to the CPU state and possibly to store a pointer
542   to a register window.
543
544 - Use temporaries. Use local temporaries only when really needed,
545   e.g. when you need to use a value after a jump. Local temporaries
546   introduce a performance hit in the current TCG implementation: their
547   content is saved to memory at end of each basic block.
548
549 - Free temporaries and local temporaries when they are no longer used
550   (tcg_temp_free). Since tcg_const_x() also creates a temporary, you
551   should free it after it is used. Freeing temporaries does not yield
552   a better generated code, but it reduces the memory usage of TCG and
553   the speed of the translation.
554
555 - Don't hesitate to use helpers for complicated or seldom used guest
556   instructions. There is little performance advantage in using TCG to
557   implement guest instructions taking more than about twenty TCG
558   instructions. Note that this rule of thumb is more applicable to
559   helpers doing complex logic or arithmetic, where the C compiler has
560   scope to do a good job of optimisation; it is less relevant where
561   the instruction is mostly doing loads and stores, and in those cases
562   inline TCG may still be faster for longer sequences.
563
564 - The hard limit on the number of TCG instructions you can generate
565   per guest instruction is set by MAX_OP_PER_INSTR in exec-all.h --
566   you cannot exceed this without risking a buffer overrun.
567
568 - Use the 'discard' instruction if you know that TCG won't be able to
569   prove that a given global is "dead" at a given program point. The
570   x86 guest uses it to improve the condition codes optimisation.