1//===------------------ mach-o/compact_unwind_encoding.h ------------------===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is dual licensed under the MIT and the University of Illinois Open 6// Source Licenses. See LICENSE.TXT for details. 7// 8// 9// Darwin's alternative to dwarf based unwind encodings. 10// 11//===----------------------------------------------------------------------===// 12 13 14#ifndef __COMPACT_UNWIND_ENCODING__ 15#define __COMPACT_UNWIND_ENCODING__ 16 17#include <stdint.h> 18 19// 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. 23// 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. 31// 32// Note: Previously, the linker would transform some dwarf unwind infos into 33// compact unwind info. But that is fragile and no longer done. 34 35 36// 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. 40// 41typedef uint32_t compact_unwind_encoding_t; 42 43 44// architecture independent bits 45enum { 46 UNWIND_IS_NOT_FUNCTION_START = 0x80000000, 47 UNWIND_HAS_LSDA = 0x40000000, 48 UNWIND_PERSONALITY_MASK = 0x30000000, 49}; 50 51 52 53 54// 55// x86 56// 57// 1-bit: start 58// 1-bit: has lsda 59// 2-bit: personality index 60// 61// 4-bits: 0=old, 1=ebp based, 2=stack-imm, 3=stack-ind, 4=dwarf 62// ebp based: 63// 15-bits (5*3-bits per reg) register permutation 64// 8-bits for stack offset 65// frameless: 66// 8-bits stack size 67// 3-bits stack adjust 68// 3-bits register count 69// 10-bits register permutation 70// 71enum { 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, 77 78 UNWIND_X86_EBP_FRAME_REGISTERS = 0x00007FFF, 79 UNWIND_X86_EBP_FRAME_OFFSET = 0x00FF0000, 80 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, 85 86 UNWIND_X86_DWARF_SECTION_OFFSET = 0x00FFFFFF, 87}; 88 89enum { 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, 97}; 98 99// 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 134// function. 135// 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. 139// 140//uint32_t permute_encode(uint32_t registerCount, const uint32_t registers[6]) 141//{ 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] ) 147// ++countless; 148// } 149// renumregs[i] = registers[i] - countless -1; 150// } 151// uint32_t permutationEncoding = 0; 152// switch ( registerCount ) { 153// case 6: 154// permutationEncoding |= (120*renumregs[0] + 24*renumregs[1] 155// + 6*renumregs[2] + 2*renumregs[3] 156// + renumregs[4]); 157// break; 158// case 5: 159// permutationEncoding |= (120*renumregs[1] + 24*renumregs[2] 160// + 6*renumregs[3] + 2*renumregs[4] 161// + renumregs[5]); 162// break; 163// case 4: 164// permutationEncoding |= (60*renumregs[2] + 12*renumregs[3] 165// + 3*renumregs[4] + renumregs[5]); 166// break; 167// case 3: 168// permutationEncoding |= (20*renumregs[3] + 4*renumregs[4] 169// + renumregs[5]); 170// break; 171// case 2: 172// permutationEncoding |= (5*renumregs[4] + renumregs[5]); 173// break; 174// case 1: 175// permutationEncoding |= (renumregs[5]); 176// break; 177// } 178// return permutationEncoding; 179//} 180// 181 182 183 184 185// 186// x86_64 187// 188// 1-bit: start 189// 1-bit: has lsda 190// 2-bit: personality index 191// 192// 4-bits: 0=old, 1=rbp based, 2=stack-imm, 3=stack-ind, 4=dwarf 193// rbp based: 194// 15-bits (5*3-bits per reg) register permutation 195// 8-bits for stack offset 196// frameless: 197// 8-bits stack size 198// 3-bits stack adjust 199// 3-bits register count 200// 10-bits register permutation 201// 202enum { 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, 208 209 UNWIND_X86_64_RBP_FRAME_REGISTERS = 0x00007FFF, 210 UNWIND_X86_64_RBP_FRAME_OFFSET = 0x00FF0000, 211 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, 216 217 UNWIND_X86_64_DWARF_SECTION_OFFSET = 0x00FFFFFF, 218}; 219 220enum { 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, 228}; 229// 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 264// function. 265// 266 267 268// ARM64 269// 270// 1-bit: start 271// 1-bit: has lsda 272// 2-bit: personality index 273// 274// 4-bits: 4=frame-based, 3=dwarf, 2=frameless 275// frameless: 276// 12-bits of stack size 277// frame-based: 278// 4-bits D reg pairs saved 279// 5-bits X reg pairs saved 280// dwarf: 281// 24-bits offset of dwarf FDE in __eh_frame section 282// 283enum { 284 UNWIND_ARM64_MODE_MASK = 0x0F000000, 285 UNWIND_ARM64_MODE_FRAMELESS = 0x02000000, 286 UNWIND_ARM64_MODE_DWARF = 0x03000000, 287 UNWIND_ARM64_MODE_FRAME = 0x04000000, 288 289 UNWIND_ARM64_FRAME_X19_X20_PAIR = 0x00000001, 290 UNWIND_ARM64_FRAME_X21_X22_PAIR = 0x00000002, 291 UNWIND_ARM64_FRAME_X23_X24_PAIR = 0x00000004, 292 UNWIND_ARM64_FRAME_X25_X26_PAIR = 0x00000008, 293 UNWIND_ARM64_FRAME_X27_X28_PAIR = 0x00000010, 294 UNWIND_ARM64_FRAME_D8_D9_PAIR = 0x00000100, 295 UNWIND_ARM64_FRAME_D10_D11_PAIR = 0x00000200, 296 UNWIND_ARM64_FRAME_D12_D13_PAIR = 0x00000400, 297 UNWIND_ARM64_FRAME_D14_D15_PAIR = 0x00000800, 298 299 UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK = 0x00FFF000, 300 UNWIND_ARM64_DWARF_SECTION_OFFSET = 0x00FFFFFF, 301}; 302// For arm64 there are three modes for the compact unwind encoding: 303// UNWIND_ARM64_MODE_FRAME: 304// This is a standard arm64 prolog where FP/LR are immediately pushed on the 305// stack, then SP is copied to FP. If there are any non-volatile registers 306// saved, then are copied into the stack frame in pairs in a contiguous 307// range right below the saved FP/LR pair. Any subset of the five X pairs 308// and four D pairs can be saved, but the memory layout must be in register 309// number order. 310// UNWIND_ARM64_MODE_FRAMELESS: 311// A "frameless" leaf function, where FP/LR are not saved. The return address 312// remains in LR throughout the function. If any non-volatile registers 313// are saved, they must be pushed onto the stack before any stack space is 314// allocated for local variables. The stack sized (including any saved 315// non-volatile registers) divided by 16 is encoded in the bits 316// UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK. 317// UNWIND_ARM64_MODE_DWARF: 318// No compact unwind encoding is available. Instead the low 24-bits of the 319// compact encoding is the offset of the dwarf FDE in the __eh_frame section. 320// This mode is never used in object files. It is only generated by the 321// linker in final linked images which have only dwarf unwind info for a 322// function. 323// 324 325 326 327 328 329//////////////////////////////////////////////////////////////////////////////// 330// 331// Relocatable Object Files: __LD,__compact_unwind 332// 333//////////////////////////////////////////////////////////////////////////////// 334 335// 336// A compiler can generated compact unwind information for a function by adding 337// a "row" to the __LD,__compact_unwind section. This section has the 338// S_ATTR_DEBUG bit set, so the section will be ignored by older linkers. 339// It is removed by the new linker, so never ends up in final executables. 340// This section is a table, initially with one row per function (that needs 341// unwind info). The table columns and some conceptual entries are: 342// 343// range-start pointer to start of function/range 344// range-length 345// compact-unwind-encoding 32-bit encoding 346// personality-function or zero if no personality function 347// lsda or zero if no LSDA data 348// 349// The length and encoding fields are 32-bits. The other are all pointer sized. 350// 351// In x86_64 assembly, these entry would look like: 352// 353// .section __LD,__compact_unwind,regular,debug 354// 355// #compact unwind for _foo 356// .quad _foo 357// .set L1,LfooEnd-_foo 358// .long L1 359// .long 0x01010001 360// .quad 0 361// .quad 0 362// 363// #compact unwind for _bar 364// .quad _bar 365// .set L2,LbarEnd-_bar 366// .long L2 367// .long 0x01020011 368// .quad __gxx_personality 369// .quad except_tab1 370// 371// 372// Notes: There is no need for any labels in the the __compact_unwind section. 373// The use of the .set directive is to force the evaluation of the 374// range-length at assembly time, instead of generating relocations. 375// 376// To support future compiler optimizations where which non-volatile registers 377// are saved changes within a function (e.g. delay saving non-volatiles until 378// necessary), there can by multiple lines in the __compact_unwind table for one 379// function, each with a different (non-overlapping) range and each with 380// different compact unwind encodings that correspond to the non-volatiles 381// saved at that range of the function. 382// 383// If a particular function is so wacky that there is no compact unwind way 384// to encode it, then the compiler can emit traditional dwarf unwind info. 385// The runtime will use which ever is available. 386// 387// Runtime support for compact unwind encodings are only available on 10.6 388// and later. So, the compiler should not generate it when targeting pre-10.6. 389 390 391 392 393//////////////////////////////////////////////////////////////////////////////// 394// 395// Final Linked Images: __TEXT,__unwind_info 396// 397//////////////////////////////////////////////////////////////////////////////// 398 399// 400// The __TEXT,__unwind_info section is laid out for an efficient two level lookup. 401// The header of the section contains a coarse index that maps function address 402// to the page (4096 byte block) containing the unwind info for that function. 403// 404 405#define UNWIND_SECTION_VERSION 1 406struct unwind_info_section_header 407{ 408 uint32_t version; // UNWIND_SECTION_VERSION 409 uint32_t commonEncodingsArraySectionOffset; 410 uint32_t commonEncodingsArrayCount; 411 uint32_t personalityArraySectionOffset; 412 uint32_t personalityArrayCount; 413 uint32_t indexSectionOffset; 414 uint32_t indexCount; 415 // compact_unwind_encoding_t[] 416 // uintptr_t personalities[] 417 // unwind_info_section_header_index_entry[] 418 // unwind_info_section_header_lsda_index_entry[] 419}; 420 421struct unwind_info_section_header_index_entry 422{ 423 uint32_t functionOffset; 424 uint32_t secondLevelPagesSectionOffset; // section offset to start of regular or compress page 425 uint32_t lsdaIndexArraySectionOffset; // section offset to start of lsda_index array for this range 426}; 427 428struct unwind_info_section_header_lsda_index_entry 429{ 430 uint32_t functionOffset; 431 uint32_t lsdaOffset; 432}; 433 434// 435// There are two kinds of second level index pages: regular and compressed. 436// A compressed page can hold up to 1021 entries, but it cannot be used 437// if too many different encoding types are used. The regular page holds 438// 511 entries. 439// 440 441struct unwind_info_regular_second_level_entry 442{ 443 uint32_t functionOffset; 444 compact_unwind_encoding_t encoding; 445}; 446 447#define UNWIND_SECOND_LEVEL_REGULAR 2 448struct unwind_info_regular_second_level_page_header 449{ 450 uint32_t kind; // UNWIND_SECOND_LEVEL_REGULAR 451 uint16_t entryPageOffset; 452 uint16_t entryCount; 453 // entry array 454}; 455 456#define UNWIND_SECOND_LEVEL_COMPRESSED 3 457struct unwind_info_compressed_second_level_page_header 458{ 459 uint32_t kind; // UNWIND_SECOND_LEVEL_COMPRESSED 460 uint16_t entryPageOffset; 461 uint16_t entryCount; 462 uint16_t encodingsPageOffset; 463 uint16_t encodingsCount; 464 // 32-bit entry array 465 // encodings array 466}; 467 468#define UNWIND_INFO_COMPRESSED_ENTRY_FUNC_OFFSET(entry) (entry & 0x00FFFFFF) 469#define UNWIND_INFO_COMPRESSED_ENTRY_ENCODING_INDEX(entry) ((entry >> 24) & 0xFF) 470 471 472 473#endif 474 475