1 //===------------------ mach-o/compact_unwind_encoding.h ------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is dual licensed under the MIT and the University of Illinois Open
6 // Source Licenses. See LICENSE.TXT for details.
9 // Darwin's alternative to dwarf based unwind encodings.
11 //===----------------------------------------------------------------------===//
14 #ifndef __COMPACT_UNWIND_ENCODING__
15 #define __COMPACT_UNWIND_ENCODING__
20 // Compilers can emit standard Dwarf FDEs in the __TEXT,__eh_frame section
21 // of object files. Or compilers can emit compact unwind information in
22 // the __LD,__compact_unwind section.
24 // When the linker creates a final linked image, it will create a
25 // __TEXT,__unwind_info section. This section is a small and fast way for the
26 // runtime to access unwind info for any given function. If the compiler
27 // emitted compact unwind info for the function, that compact unwind info will
28 // be encoded in the __TEXT,__unwind_info section. If the compiler emitted
29 // dwarf unwind info, the __TEXT,__unwind_info section will contain the offset
30 // of the FDE in the __TEXT,__eh_frame section in the final linked image.
32 // Note: Previously, the linker would transform some dwarf unwind infos into
33 // compact unwind info. But that is fragile and no longer done.
37 // The compact unwind endoding is a 32-bit value which encoded in an
38 // architecture specific way, which registers to restore from where, and how
39 // to unwind out of the function.
41 typedef uint32_t compact_unwind_encoding_t;
44 // architecture independent bits
46 UNWIND_IS_NOT_FUNCTION_START = 0x80000000,
47 UNWIND_HAS_LSDA = 0x40000000,
48 UNWIND_PERSONALITY_MASK = 0x30000000,
59 // 2-bit: personality index
61 // 4-bits: 0=old, 1=ebp based, 2=stack-imm, 3=stack-ind, 4=dwarf
63 // 15-bits (5*3-bits per reg) register permutation
64 // 8-bits for stack offset
67 // 3-bits stack adjust
68 // 3-bits register count
69 // 10-bits register permutation
72 UNWIND_X86_MODE_MASK = 0x0F000000,
73 UNWIND_X86_MODE_EBP_FRAME = 0x01000000,
74 UNWIND_X86_MODE_STACK_IMMD = 0x02000000,
75 UNWIND_X86_MODE_STACK_IND = 0x03000000,
76 UNWIND_X86_MODE_DWARF = 0x04000000,
78 UNWIND_X86_EBP_FRAME_REGISTERS = 0x00007FFF,
79 UNWIND_X86_EBP_FRAME_OFFSET = 0x00FF0000,
81 UNWIND_X86_FRAMELESS_STACK_SIZE = 0x00FF0000,
82 UNWIND_X86_FRAMELESS_STACK_ADJUST = 0x0000E000,
83 UNWIND_X86_FRAMELESS_STACK_REG_COUNT = 0x00001C00,
84 UNWIND_X86_FRAMELESS_STACK_REG_PERMUTATION = 0x000003FF,
86 UNWIND_X86_DWARF_SECTION_OFFSET = 0x00FFFFFF,
90 UNWIND_X86_REG_NONE = 0,
91 UNWIND_X86_REG_EBX = 1,
92 UNWIND_X86_REG_ECX = 2,
93 UNWIND_X86_REG_EDX = 3,
94 UNWIND_X86_REG_EDI = 4,
95 UNWIND_X86_REG_ESI = 5,
96 UNWIND_X86_REG_EBP = 6,
100 // For x86 there are four modes for the compact unwind encoding:
101 // UNWIND_X86_MODE_EBP_FRAME:
102 // EBP based frame where EBP is push on stack immediately after return address,
103 // then ESP is moved to EBP. Thus, to unwind ESP is restored with the current
104 // EPB value, then EBP is restored by popping off the stack, and the return
105 // is done by popping the stack once more into the pc.
106 // All non-volatile registers that need to be restored must have been saved
107 // in a small range in the stack that starts EBP-4 to EBP-1020. The offset/4
108 // is encoded in the UNWIND_X86_EBP_FRAME_OFFSET bits. The registers saved
109 // are encoded in the UNWIND_X86_EBP_FRAME_REGISTERS bits as five 3-bit entries.
110 // Each entry contains which register to restore.
111 // UNWIND_X86_MODE_STACK_IMMD:
112 // A "frameless" (EBP not used as frame pointer) function with a small
113 // constant stack size. To return, a constant (encoded in the compact
114 // unwind encoding) is added to the ESP. Then the return is done by
115 // popping the stack into the pc.
116 // All non-volatile registers that need to be restored must have been saved
117 // on the stack immediately after the return address. The stack_size/4 is
118 // encoded in the UNWIND_X86_FRAMELESS_STACK_SIZE (max stack size is 1024).
119 // The number of registers saved is encoded in UNWIND_X86_FRAMELESS_STACK_REG_COUNT.
120 // UNWIND_X86_FRAMELESS_STACK_REG_PERMUTATION constains which registers were
121 // saved and their order.
122 // UNWIND_X86_MODE_STACK_IND:
123 // A "frameless" (EBP not used as frame pointer) function large constant
124 // stack size. This case is like the previous, except the stack size is too
125 // large to encode in the compact unwind encoding. Instead it requires that
126 // the function contains "subl $nnnnnnnn,ESP" in its prolog. The compact
127 // encoding contains the offset to the nnnnnnnn value in the function in
128 // UNWIND_X86_FRAMELESS_STACK_SIZE.
129 // UNWIND_X86_MODE_DWARF:
130 // No compact unwind encoding is available. Instead the low 24-bits of the
131 // compact encoding is the offset of the dwarf FDE in the __eh_frame section.
132 // This mode is never used in object files. It is only generated by the
133 // linker in final linked images which have only dwarf unwind info for a
136 // The following is the algorithm used to create the permutation encoding used
137 // with frameless stacks. It is passed the number of registers to be saved and
138 // an array of the register numbers saved.
140 //uint32_t permute_encode(uint32_t registerCount, const uint32_t registers[6])
142 // uint32_t renumregs[6];
143 // for (int i=6-registerCount; i < 6; ++i) {
144 // int countless = 0;
145 // for (int j=6-registerCount; j < i; ++j) {
146 // if ( registers[j] < registers[i] )
149 // renumregs[i] = registers[i] - countless -1;
151 // uint32_t permutationEncoding = 0;
152 // switch ( registerCount ) {
154 // permutationEncoding |= (120*renumregs[0] + 24*renumregs[1]
155 // + 6*renumregs[2] + 2*renumregs[3]
159 // permutationEncoding |= (120*renumregs[1] + 24*renumregs[2]
160 // + 6*renumregs[3] + 2*renumregs[4]
164 // permutationEncoding |= (60*renumregs[2] + 12*renumregs[3]
165 // + 3*renumregs[4] + renumregs[5]);
168 // permutationEncoding |= (20*renumregs[3] + 4*renumregs[4]
172 // permutationEncoding |= (5*renumregs[4] + renumregs[5]);
175 // permutationEncoding |= (renumregs[5]);
178 // return permutationEncoding;
190 // 2-bit: personality index
192 // 4-bits: 0=old, 1=rbp based, 2=stack-imm, 3=stack-ind, 4=dwarf
194 // 15-bits (5*3-bits per reg) register permutation
195 // 8-bits for stack offset
198 // 3-bits stack adjust
199 // 3-bits register count
200 // 10-bits register permutation
203 UNWIND_X86_64_MODE_MASK = 0x0F000000,
204 UNWIND_X86_64_MODE_RBP_FRAME = 0x01000000,
205 UNWIND_X86_64_MODE_STACK_IMMD = 0x02000000,
206 UNWIND_X86_64_MODE_STACK_IND = 0x03000000,
207 UNWIND_X86_64_MODE_DWARF = 0x04000000,
209 UNWIND_X86_64_RBP_FRAME_REGISTERS = 0x00007FFF,
210 UNWIND_X86_64_RBP_FRAME_OFFSET = 0x00FF0000,
212 UNWIND_X86_64_FRAMELESS_STACK_SIZE = 0x00FF0000,
213 UNWIND_X86_64_FRAMELESS_STACK_ADJUST = 0x0000E000,
214 UNWIND_X86_64_FRAMELESS_STACK_REG_COUNT = 0x00001C00,
215 UNWIND_X86_64_FRAMELESS_STACK_REG_PERMUTATION = 0x000003FF,
217 UNWIND_X86_64_DWARF_SECTION_OFFSET = 0x00FFFFFF,
221 UNWIND_X86_64_REG_NONE = 0,
222 UNWIND_X86_64_REG_RBX = 1,
223 UNWIND_X86_64_REG_R12 = 2,
224 UNWIND_X86_64_REG_R13 = 3,
225 UNWIND_X86_64_REG_R14 = 4,
226 UNWIND_X86_64_REG_R15 = 5,
227 UNWIND_X86_64_REG_RBP = 6,
230 // For x86_64 there are four modes for the compact unwind encoding:
231 // UNWIND_X86_64_MODE_RBP_FRAME:
232 // RBP based frame where RBP is push on stack immediately after return address,
233 // then RSP is moved to RBP. Thus, to unwind RSP is restored with the current
234 // EPB value, then RBP is restored by popping off the stack, and the return
235 // is done by popping the stack once more into the pc.
236 // All non-volatile registers that need to be restored must have been saved
237 // in a small range in the stack that starts RBP-8 to RBP-1020. The offset/4
238 // is encoded in the UNWIND_X86_64_RBP_FRAME_OFFSET bits. The registers saved
239 // are encoded in the UNWIND_X86_64_RBP_FRAME_REGISTERS bits as five 3-bit entries.
240 // Each entry contains which register to restore.
241 // UNWIND_X86_64_MODE_STACK_IMMD:
242 // A "frameless" (RBP not used as frame pointer) function with a small
243 // constant stack size. To return, a constant (encoded in the compact
244 // unwind encoding) is added to the RSP. Then the return is done by
245 // popping the stack into the pc.
246 // All non-volatile registers that need to be restored must have been saved
247 // on the stack immediately after the return address. The stack_size/4 is
248 // encoded in the UNWIND_X86_64_FRAMELESS_STACK_SIZE (max stack size is 1024).
249 // The number of registers saved is encoded in UNWIND_X86_64_FRAMELESS_STACK_REG_COUNT.
250 // UNWIND_X86_64_FRAMELESS_STACK_REG_PERMUTATION constains which registers were
251 // saved and their order.
252 // UNWIND_X86_64_MODE_STACK_IND:
253 // A "frameless" (RBP not used as frame pointer) function large constant
254 // stack size. This case is like the previous, except the stack size is too
255 // large to encode in the compact unwind encoding. Instead it requires that
256 // the function contains "subq $nnnnnnnn,RSP" in its prolog. The compact
257 // encoding contains the offset to the nnnnnnnn value in the function in
258 // UNWIND_X86_64_FRAMELESS_STACK_SIZE.
259 // UNWIND_X86_64_MODE_DWARF:
260 // No compact unwind encoding is available. Instead the low 24-bits of the
261 // compact encoding is the offset of the dwarf FDE in the __eh_frame section.
262 // This mode is never used in object files. It is only generated by the
263 // linker in final linked images which have only dwarf unwind info for a
268 #ifndef __OPEN_SOURCE__
274 // 2-bit: personality index
276 // 4-bits: 4=frame-based, 2=frameless, 3=dwarf
278 // 12-bits of stack size
280 // 4-bits D reg pairs saved
281 // 5-bits X reg pairs saved
283 // 24-bits offset of dwarf FDE in __eh_frame section
286 UNWIND_ARM64_MODE_MASK = 0x0F000000,
287 UNWIND_ARM64_MODE_FRAMELESS = 0x02000000,
288 UNWIND_ARM64_MODE_DWARF = 0x03000000,
289 UNWIND_ARM64_MODE_FRAME = 0x04000000,
291 UNWIND_ARM64_FRAME_X19_X20_PAIR = 0x00000001,
292 UNWIND_ARM64_FRAME_X21_X22_PAIR = 0x00000002,
293 UNWIND_ARM64_FRAME_X23_X24_PAIR = 0x00000004,
294 UNWIND_ARM64_FRAME_X25_X26_PAIR = 0x00000008,
295 UNWIND_ARM64_FRAME_X27_X28_PAIR = 0x00000010,
296 UNWIND_ARM64_FRAME_D8_D9_PAIR = 0x00000100,
297 UNWIND_ARM64_FRAME_D10_D11_PAIR = 0x00000200,
298 UNWIND_ARM64_FRAME_D12_D13_PAIR = 0x00000400,
299 UNWIND_ARM64_FRAME_D14_D15_PAIR = 0x00000800,
301 UNWIND_ARM64_FRAME_X21_X22_PAIR_OLD = 0x00000001,
302 UNWIND_ARM64_FRAME_X23_X24_PAIR_OLD = 0x00000002,
303 UNWIND_ARM64_FRAME_X25_X26_PAIR_OLD = 0x00000004,
304 UNWIND_ARM64_FRAME_X27_X28_PAIR_OLD = 0x00000008,
305 UNWIND_ARM64_FRAME_D8_D9_PAIR_OLD = 0x00000010,
306 UNWIND_ARM64_FRAME_D10_D11_PAIR_OLD = 0x00000020,
307 UNWIND_ARM64_FRAME_D12_D13_PAIR_OLD = 0x00000040,
308 UNWIND_ARM64_FRAME_D14_D15_PAIR_OLD = 0x00000080,
310 UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK = 0x00FFF000,
311 UNWIND_ARM64_DWARF_SECTION_OFFSET = 0x00FFFFFF,
313 // For arm64 there are three modes for the compact unwind encoding:
314 // UNWIND_ARM64_MODE_FRAME:
315 // This is a standard arm64 prolog where FP/LR are immediately pushed on the
316 // stack, then SP is copied to FP. If there are any non-volatile registers
317 // saved, then are copied into the stack frame in pairs in a contiguous
318 // range right below the saved FP/LR pair. Any subset of the five X pairs
319 // and four D pairs can be saved, but the memory layout must be in register
321 // UNWIND_ARM64_MODE_FRAMELESS:
322 // A "frameless" leaf function, where FP/LR are not saved. The return address
323 // remains in LR throughout the function. If any non-volatile registers
324 // are saved, they must be pushed onto the stack before any stack space is
325 // allocated for local variables. The stack sized (including any saved
326 // non-volatile registers) divided by 16 is encoded in the bits
327 // UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK.
328 // UNWIND_ARM64_MODE_DWARF:
329 // No compact unwind encoding is available. Instead the low 24-bits of the
330 // compact encoding is the offset of the dwarf FDE in the __eh_frame section.
331 // This mode is never used in object files. It is only generated by the
332 // linker in final linked images which have only dwarf unwind info for a
336 #endif // __OPEN_SOURCE__
342 ////////////////////////////////////////////////////////////////////////////////
344 // Relocatable Object Files: __LD,__compact_unwind
346 ////////////////////////////////////////////////////////////////////////////////
349 // A compiler can generated compact unwind information for a function by adding
350 // a "row" to the __LD,__compact_unwind section. This section has the
351 // S_ATTR_DEBUG bit set, so the section will be ignored by older linkers.
352 // It is removed by the new linker, so never ends up in final executables.
353 // This section is a table, initially with one row per function (that needs
354 // unwind info). The table columns and some conceptual entries are:
356 // range-start pointer to start of function/range
358 // compact-unwind-encoding 32-bit encoding
359 // personality-function or zero if no personality function
360 // lsda or zero if no LSDA data
362 // The length and encoding fields are 32-bits. The other are all pointer sized.
364 // In x86_64 assembly, these entry would look like:
366 // .section __LD,__compact_unwind,regular,debug
368 // #compact unwind for _foo
370 // .set L1,LfooEnd-_foo
376 // #compact unwind for _bar
378 // .set L2,LbarEnd-_bar
381 // .quad __gxx_personality
385 // Notes: There is no need for any labels in the the __compact_unwind section.
386 // The use of the .set directive is to force the evaluation of the
387 // range-length at assembly time, instead of generating relocations.
389 // To support future compiler optimizations where which non-volatile registers
390 // are saved changes within a function (e.g. delay saving non-volatiles until
391 // necessary), there can by multiple lines in the __compact_unwind table for one
392 // function, each with a different (non-overlapping) range and each with
393 // different compact unwind encodings that correspond to the non-volatiles
394 // saved at that range of the function.
396 // If a particular function is so wacky that there is no compact unwind way
397 // to encode it, then the compiler can emit traditional dwarf unwind info.
398 // The runtime will use which ever is available.
400 // Runtime support for compact unwind encodings are only available on 10.6
401 // and later. So, the compiler should not generate it when targeting pre-10.6.
406 ////////////////////////////////////////////////////////////////////////////////
408 // Final Linked Images: __TEXT,__unwind_info
410 ////////////////////////////////////////////////////////////////////////////////
413 // The __TEXT,__unwind_info section is laid out for an efficient two level lookup.
414 // The header of the section contains a coarse index that maps function address
415 // to the page (4096 byte block) containing the unwind info for that function.
418 #define UNWIND_SECTION_VERSION 1
419 struct unwind_info_section_header
421 uint32_t version; // UNWIND_SECTION_VERSION
422 uint32_t commonEncodingsArraySectionOffset;
423 uint32_t commonEncodingsArrayCount;
424 uint32_t personalityArraySectionOffset;
425 uint32_t personalityArrayCount;
426 uint32_t indexSectionOffset;
428 // compact_unwind_encoding_t[]
429 // uintptr_t personalities[]
430 // unwind_info_section_header_index_entry[]
431 // unwind_info_section_header_lsda_index_entry[]
434 struct unwind_info_section_header_index_entry
436 uint32_t functionOffset;
437 uint32_t secondLevelPagesSectionOffset; // section offset to start of regular or compress page
438 uint32_t lsdaIndexArraySectionOffset; // section offset to start of lsda_index array for this range
441 struct unwind_info_section_header_lsda_index_entry
443 uint32_t functionOffset;
448 // There are two kinds of second level index pages: regular and compressed.
449 // A compressed page can hold up to 1021 entries, but it cannot be used
450 // if too many different encoding types are used. The regular page holds
454 struct unwind_info_regular_second_level_entry
456 uint32_t functionOffset;
457 compact_unwind_encoding_t encoding;
460 #define UNWIND_SECOND_LEVEL_REGULAR 2
461 struct unwind_info_regular_second_level_page_header
463 uint32_t kind; // UNWIND_SECOND_LEVEL_REGULAR
464 uint16_t entryPageOffset;
469 #define UNWIND_SECOND_LEVEL_COMPRESSED 3
470 struct unwind_info_compressed_second_level_page_header
472 uint32_t kind; // UNWIND_SECOND_LEVEL_COMPRESSED
473 uint16_t entryPageOffset;
475 uint16_t encodingsPageOffset;
476 uint16_t encodingsCount;
477 // 32-bit entry array
481 #define UNWIND_INFO_COMPRESSED_ENTRY_FUNC_OFFSET(entry) (entry & 0x00FFFFFF)
482 #define UNWIND_INFO_COMPRESSED_ENTRY_ENCODING_INDEX(entry) ((entry >> 24) & 0xFF)