compact_unwind_encoding.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477
  1. //===----------------------------------------------------------------------===//
  2. //
  3. // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
  4. // See https://llvm.org/LICENSE.txt for license information.
  5. // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  6. //
  7. //
  8. // Darwin's alternative to DWARF based unwind encodings.
  9. //
  10. //===----------------------------------------------------------------------===//
  11. #ifndef __COMPACT_UNWIND_ENCODING__
  12. #define __COMPACT_UNWIND_ENCODING__
  13. #include <stdint.h>
  14. //
  15. // Compilers can emit standard DWARF FDEs in the __TEXT,__eh_frame section
  16. // of object files. Or compilers can emit compact unwind information in
  17. // the __LD,__compact_unwind section.
  18. //
  19. // When the linker creates a final linked image, it will create a
  20. // __TEXT,__unwind_info section. This section is a small and fast way for the
  21. // runtime to access unwind info for any given function. If the compiler
  22. // emitted compact unwind info for the function, that compact unwind info will
  23. // be encoded in the __TEXT,__unwind_info section. If the compiler emitted
  24. // DWARF unwind info, the __TEXT,__unwind_info section will contain the offset
  25. // of the FDE in the __TEXT,__eh_frame section in the final linked image.
  26. //
  27. // Note: Previously, the linker would transform some DWARF unwind infos into
  28. // compact unwind info. But that is fragile and no longer done.
  29. //
  30. // The compact unwind encoding is a 32-bit value which encoded in an
  31. // architecture specific way, which registers to restore from where, and how
  32. // to unwind out of the function.
  33. //
  34. typedef uint32_t compact_unwind_encoding_t;
  35. // architecture independent bits
  36. enum {
  37. UNWIND_IS_NOT_FUNCTION_START = 0x80000000,
  38. UNWIND_HAS_LSDA = 0x40000000,
  39. UNWIND_PERSONALITY_MASK = 0x30000000,
  40. };
  41. //
  42. // x86
  43. //
  44. // 1-bit: start
  45. // 1-bit: has lsda
  46. // 2-bit: personality index
  47. //
  48. // 4-bits: 0=old, 1=ebp based, 2=stack-imm, 3=stack-ind, 4=DWARF
  49. // ebp based:
  50. // 15-bits (5*3-bits per reg) register permutation
  51. // 8-bits for stack offset
  52. // frameless:
  53. // 8-bits stack size
  54. // 3-bits stack adjust
  55. // 3-bits register count
  56. // 10-bits register permutation
  57. //
  58. enum {
  59. UNWIND_X86_MODE_MASK = 0x0F000000,
  60. UNWIND_X86_MODE_EBP_FRAME = 0x01000000,
  61. UNWIND_X86_MODE_STACK_IMMD = 0x02000000,
  62. UNWIND_X86_MODE_STACK_IND = 0x03000000,
  63. UNWIND_X86_MODE_DWARF = 0x04000000,
  64. UNWIND_X86_EBP_FRAME_REGISTERS = 0x00007FFF,
  65. UNWIND_X86_EBP_FRAME_OFFSET = 0x00FF0000,
  66. UNWIND_X86_FRAMELESS_STACK_SIZE = 0x00FF0000,
  67. UNWIND_X86_FRAMELESS_STACK_ADJUST = 0x0000E000,
  68. UNWIND_X86_FRAMELESS_STACK_REG_COUNT = 0x00001C00,
  69. UNWIND_X86_FRAMELESS_STACK_REG_PERMUTATION = 0x000003FF,
  70. UNWIND_X86_DWARF_SECTION_OFFSET = 0x00FFFFFF,
  71. };
  72. enum {
  73. UNWIND_X86_REG_NONE = 0,
  74. UNWIND_X86_REG_EBX = 1,
  75. UNWIND_X86_REG_ECX = 2,
  76. UNWIND_X86_REG_EDX = 3,
  77. UNWIND_X86_REG_EDI = 4,
  78. UNWIND_X86_REG_ESI = 5,
  79. UNWIND_X86_REG_EBP = 6,
  80. };
  81. //
  82. // For x86 there are four modes for the compact unwind encoding:
  83. // UNWIND_X86_MODE_EBP_FRAME:
  84. // EBP based frame where EBP is push on stack immediately after return address,
  85. // then ESP is moved to EBP. Thus, to unwind ESP is restored with the current
  86. // EPB value, then EBP is restored by popping off the stack, and the return
  87. // is done by popping the stack once more into the pc.
  88. // All non-volatile registers that need to be restored must have been saved
  89. // in a small range in the stack that starts EBP-4 to EBP-1020. The offset/4
  90. // is encoded in the UNWIND_X86_EBP_FRAME_OFFSET bits. The registers saved
  91. // are encoded in the UNWIND_X86_EBP_FRAME_REGISTERS bits as five 3-bit entries.
  92. // Each entry contains which register to restore.
  93. // UNWIND_X86_MODE_STACK_IMMD:
  94. // A "frameless" (EBP not used as frame pointer) function with a small
  95. // constant stack size. To return, a constant (encoded in the compact
  96. // unwind encoding) is added to the ESP. Then the return is done by
  97. // popping the stack into the pc.
  98. // All non-volatile registers that need to be restored must have been saved
  99. // on the stack immediately after the return address. The stack_size/4 is
  100. // encoded in the UNWIND_X86_FRAMELESS_STACK_SIZE (max stack size is 1024).
  101. // The number of registers saved is encoded in UNWIND_X86_FRAMELESS_STACK_REG_COUNT.
  102. // UNWIND_X86_FRAMELESS_STACK_REG_PERMUTATION contains which registers were
  103. // saved and their order.
  104. // UNWIND_X86_MODE_STACK_IND:
  105. // A "frameless" (EBP not used as frame pointer) function large constant
  106. // stack size. This case is like the previous, except the stack size is too
  107. // large to encode in the compact unwind encoding. Instead it requires that
  108. // the function contains "subl $nnnnnnnn,ESP" in its prolog. The compact
  109. // encoding contains the offset to the nnnnnnnn value in the function in
  110. // UNWIND_X86_FRAMELESS_STACK_SIZE.
  111. // UNWIND_X86_MODE_DWARF:
  112. // No compact unwind encoding is available. Instead the low 24-bits of the
  113. // compact encoding is the offset of the DWARF FDE in the __eh_frame section.
  114. // This mode is never used in object files. It is only generated by the
  115. // linker in final linked images which have only DWARF unwind info for a
  116. // function.
  117. //
  118. // The permutation encoding is a Lehmer code sequence encoded into a
  119. // single variable-base number so we can encode the ordering of up to
  120. // six registers in a 10-bit space.
  121. //
  122. // The following is the algorithm used to create the permutation encoding used
  123. // with frameless stacks. It is passed the number of registers to be saved and
  124. // an array of the register numbers saved.
  125. //
  126. //uint32_t permute_encode(uint32_t registerCount, const uint32_t registers[6])
  127. //{
  128. // uint32_t renumregs[6];
  129. // for (int i=6-registerCount; i < 6; ++i) {
  130. // int countless = 0;
  131. // for (int j=6-registerCount; j < i; ++j) {
  132. // if ( registers[j] < registers[i] )
  133. // ++countless;
  134. // }
  135. // renumregs[i] = registers[i] - countless -1;
  136. // }
  137. // uint32_t permutationEncoding = 0;
  138. // switch ( registerCount ) {
  139. // case 6:
  140. // permutationEncoding |= (120*renumregs[0] + 24*renumregs[1]
  141. // + 6*renumregs[2] + 2*renumregs[3]
  142. // + renumregs[4]);
  143. // break;
  144. // case 5:
  145. // permutationEncoding |= (120*renumregs[1] + 24*renumregs[2]
  146. // + 6*renumregs[3] + 2*renumregs[4]
  147. // + renumregs[5]);
  148. // break;
  149. // case 4:
  150. // permutationEncoding |= (60*renumregs[2] + 12*renumregs[3]
  151. // + 3*renumregs[4] + renumregs[5]);
  152. // break;
  153. // case 3:
  154. // permutationEncoding |= (20*renumregs[3] + 4*renumregs[4]
  155. // + renumregs[5]);
  156. // break;
  157. // case 2:
  158. // permutationEncoding |= (5*renumregs[4] + renumregs[5]);
  159. // break;
  160. // case 1:
  161. // permutationEncoding |= (renumregs[5]);
  162. // break;
  163. // }
  164. // return permutationEncoding;
  165. //}
  166. //
  167. //
  168. // x86_64
  169. //
  170. // 1-bit: start
  171. // 1-bit: has lsda
  172. // 2-bit: personality index
  173. //
  174. // 4-bits: 0=old, 1=rbp based, 2=stack-imm, 3=stack-ind, 4=DWARF
  175. // rbp based:
  176. // 15-bits (5*3-bits per reg) register permutation
  177. // 8-bits for stack offset
  178. // frameless:
  179. // 8-bits stack size
  180. // 3-bits stack adjust
  181. // 3-bits register count
  182. // 10-bits register permutation
  183. //
  184. enum {
  185. UNWIND_X86_64_MODE_MASK = 0x0F000000,
  186. UNWIND_X86_64_MODE_RBP_FRAME = 0x01000000,
  187. UNWIND_X86_64_MODE_STACK_IMMD = 0x02000000,
  188. UNWIND_X86_64_MODE_STACK_IND = 0x03000000,
  189. UNWIND_X86_64_MODE_DWARF = 0x04000000,
  190. UNWIND_X86_64_RBP_FRAME_REGISTERS = 0x00007FFF,
  191. UNWIND_X86_64_RBP_FRAME_OFFSET = 0x00FF0000,
  192. UNWIND_X86_64_FRAMELESS_STACK_SIZE = 0x00FF0000,
  193. UNWIND_X86_64_FRAMELESS_STACK_ADJUST = 0x0000E000,
  194. UNWIND_X86_64_FRAMELESS_STACK_REG_COUNT = 0x00001C00,
  195. UNWIND_X86_64_FRAMELESS_STACK_REG_PERMUTATION = 0x000003FF,
  196. UNWIND_X86_64_DWARF_SECTION_OFFSET = 0x00FFFFFF,
  197. };
  198. enum {
  199. UNWIND_X86_64_REG_NONE = 0,
  200. UNWIND_X86_64_REG_RBX = 1,
  201. UNWIND_X86_64_REG_R12 = 2,
  202. UNWIND_X86_64_REG_R13 = 3,
  203. UNWIND_X86_64_REG_R14 = 4,
  204. UNWIND_X86_64_REG_R15 = 5,
  205. UNWIND_X86_64_REG_RBP = 6,
  206. };
  207. //
  208. // For x86_64 there are four modes for the compact unwind encoding:
  209. // UNWIND_X86_64_MODE_RBP_FRAME:
  210. // RBP based frame where RBP is push on stack immediately after return address,
  211. // then RSP is moved to RBP. Thus, to unwind RSP is restored with the current
  212. // EPB value, then RBP is restored by popping off the stack, and the return
  213. // is done by popping the stack once more into the pc.
  214. // All non-volatile registers that need to be restored must have been saved
  215. // in a small range in the stack that starts RBP-8 to RBP-2040. The offset/8
  216. // is encoded in the UNWIND_X86_64_RBP_FRAME_OFFSET bits. The registers saved
  217. // are encoded in the UNWIND_X86_64_RBP_FRAME_REGISTERS bits as five 3-bit entries.
  218. // Each entry contains which register to restore.
  219. // UNWIND_X86_64_MODE_STACK_IMMD:
  220. // A "frameless" (RBP not used as frame pointer) function with a small
  221. // constant stack size. To return, a constant (encoded in the compact
  222. // unwind encoding) is added to the RSP. Then the return is done by
  223. // popping the stack into the pc.
  224. // All non-volatile registers that need to be restored must have been saved
  225. // on the stack immediately after the return address. The stack_size/8 is
  226. // encoded in the UNWIND_X86_64_FRAMELESS_STACK_SIZE (max stack size is 2048).
  227. // The number of registers saved is encoded in UNWIND_X86_64_FRAMELESS_STACK_REG_COUNT.
  228. // UNWIND_X86_64_FRAMELESS_STACK_REG_PERMUTATION contains which registers were
  229. // saved and their order.
  230. // UNWIND_X86_64_MODE_STACK_IND:
  231. // A "frameless" (RBP not used as frame pointer) function large constant
  232. // stack size. This case is like the previous, except the stack size is too
  233. // large to encode in the compact unwind encoding. Instead it requires that
  234. // the function contains "subq $nnnnnnnn,RSP" in its prolog. The compact
  235. // encoding contains the offset to the nnnnnnnn value in the function in
  236. // UNWIND_X86_64_FRAMELESS_STACK_SIZE.
  237. // UNWIND_X86_64_MODE_DWARF:
  238. // No compact unwind encoding is available. Instead the low 24-bits of the
  239. // compact encoding is the offset of the DWARF FDE in the __eh_frame section.
  240. // This mode is never used in object files. It is only generated by the
  241. // linker in final linked images which have only DWARF unwind info for a
  242. // function.
  243. //
  244. // ARM64
  245. //
  246. // 1-bit: start
  247. // 1-bit: has lsda
  248. // 2-bit: personality index
  249. //
  250. // 4-bits: 4=frame-based, 3=DWARF, 2=frameless
  251. // frameless:
  252. // 12-bits of stack size
  253. // frame-based:
  254. // 4-bits D reg pairs saved
  255. // 5-bits X reg pairs saved
  256. // DWARF:
  257. // 24-bits offset of DWARF FDE in __eh_frame section
  258. //
  259. enum {
  260. UNWIND_ARM64_MODE_MASK = 0x0F000000,
  261. UNWIND_ARM64_MODE_FRAMELESS = 0x02000000,
  262. UNWIND_ARM64_MODE_DWARF = 0x03000000,
  263. UNWIND_ARM64_MODE_FRAME = 0x04000000,
  264. UNWIND_ARM64_FRAME_X19_X20_PAIR = 0x00000001,
  265. UNWIND_ARM64_FRAME_X21_X22_PAIR = 0x00000002,
  266. UNWIND_ARM64_FRAME_X23_X24_PAIR = 0x00000004,
  267. UNWIND_ARM64_FRAME_X25_X26_PAIR = 0x00000008,
  268. UNWIND_ARM64_FRAME_X27_X28_PAIR = 0x00000010,
  269. UNWIND_ARM64_FRAME_D8_D9_PAIR = 0x00000100,
  270. UNWIND_ARM64_FRAME_D10_D11_PAIR = 0x00000200,
  271. UNWIND_ARM64_FRAME_D12_D13_PAIR = 0x00000400,
  272. UNWIND_ARM64_FRAME_D14_D15_PAIR = 0x00000800,
  273. UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK = 0x00FFF000,
  274. UNWIND_ARM64_DWARF_SECTION_OFFSET = 0x00FFFFFF,
  275. };
  276. // For arm64 there are three modes for the compact unwind encoding:
  277. // UNWIND_ARM64_MODE_FRAME:
  278. // This is a standard arm64 prolog where FP/LR are immediately pushed on the
  279. // stack, then SP is copied to FP. If there are any non-volatile registers
  280. // saved, then are copied into the stack frame in pairs in a contiguous
  281. // range right below the saved FP/LR pair. Any subset of the five X pairs
  282. // and four D pairs can be saved, but the memory layout must be in register
  283. // number order.
  284. // UNWIND_ARM64_MODE_FRAMELESS:
  285. // A "frameless" leaf function, where FP/LR are not saved. The return address
  286. // remains in LR throughout the function. If any non-volatile registers
  287. // are saved, they must be pushed onto the stack before any stack space is
  288. // allocated for local variables. The stack sized (including any saved
  289. // non-volatile registers) divided by 16 is encoded in the bits
  290. // UNWIND_ARM64_FRAMELESS_STACK_SIZE_MASK.
  291. // UNWIND_ARM64_MODE_DWARF:
  292. // No compact unwind encoding is available. Instead the low 24-bits of the
  293. // compact encoding is the offset of the DWARF FDE in the __eh_frame section.
  294. // This mode is never used in object files. It is only generated by the
  295. // linker in final linked images which have only DWARF unwind info for a
  296. // function.
  297. //
  298. ////////////////////////////////////////////////////////////////////////////////
  299. //
  300. // Relocatable Object Files: __LD,__compact_unwind
  301. //
  302. ////////////////////////////////////////////////////////////////////////////////
  303. //
  304. // A compiler can generated compact unwind information for a function by adding
  305. // a "row" to the __LD,__compact_unwind section. This section has the
  306. // S_ATTR_DEBUG bit set, so the section will be ignored by older linkers.
  307. // It is removed by the new linker, so never ends up in final executables.
  308. // This section is a table, initially with one row per function (that needs
  309. // unwind info). The table columns and some conceptual entries are:
  310. //
  311. // range-start pointer to start of function/range
  312. // range-length
  313. // compact-unwind-encoding 32-bit encoding
  314. // personality-function or zero if no personality function
  315. // lsda or zero if no LSDA data
  316. //
  317. // The length and encoding fields are 32-bits. The other are all pointer sized.
  318. //
  319. // In x86_64 assembly, these entry would look like:
  320. //
  321. // .section __LD,__compact_unwind,regular,debug
  322. //
  323. // #compact unwind for _foo
  324. // .quad _foo
  325. // .set L1,LfooEnd-_foo
  326. // .long L1
  327. // .long 0x01010001
  328. // .quad 0
  329. // .quad 0
  330. //
  331. // #compact unwind for _bar
  332. // .quad _bar
  333. // .set L2,LbarEnd-_bar
  334. // .long L2
  335. // .long 0x01020011
  336. // .quad __gxx_personality
  337. // .quad except_tab1
  338. //
  339. //
  340. // Notes: There is no need for any labels in the __compact_unwind section.
  341. // The use of the .set directive is to force the evaluation of the
  342. // range-length at assembly time, instead of generating relocations.
  343. //
  344. // To support future compiler optimizations where which non-volatile registers
  345. // are saved changes within a function (e.g. delay saving non-volatiles until
  346. // necessary), there can by multiple lines in the __compact_unwind table for one
  347. // function, each with a different (non-overlapping) range and each with
  348. // different compact unwind encodings that correspond to the non-volatiles
  349. // saved at that range of the function.
  350. //
  351. // If a particular function is so wacky that there is no compact unwind way
  352. // to encode it, then the compiler can emit traditional DWARF unwind info.
  353. // The runtime will use which ever is available.
  354. //
  355. // Runtime support for compact unwind encodings are only available on 10.6
  356. // and later. So, the compiler should not generate it when targeting pre-10.6.
  357. ////////////////////////////////////////////////////////////////////////////////
  358. //
  359. // Final Linked Images: __TEXT,__unwind_info
  360. //
  361. ////////////////////////////////////////////////////////////////////////////////
  362. //
  363. // The __TEXT,__unwind_info section is laid out for an efficient two level lookup.
  364. // The header of the section contains a coarse index that maps function address
  365. // to the page (4096 byte block) containing the unwind info for that function.
  366. //
  367. #define UNWIND_SECTION_VERSION 1
  368. struct unwind_info_section_header
  369. {
  370. uint32_t version; // UNWIND_SECTION_VERSION
  371. uint32_t commonEncodingsArraySectionOffset;
  372. uint32_t commonEncodingsArrayCount;
  373. uint32_t personalityArraySectionOffset;
  374. uint32_t personalityArrayCount;
  375. uint32_t indexSectionOffset;
  376. uint32_t indexCount;
  377. // compact_unwind_encoding_t[]
  378. // uint32_t personalities[]
  379. // unwind_info_section_header_index_entry[]
  380. // unwind_info_section_header_lsda_index_entry[]
  381. };
  382. struct unwind_info_section_header_index_entry
  383. {
  384. uint32_t functionOffset;
  385. uint32_t secondLevelPagesSectionOffset; // section offset to start of regular or compress page
  386. uint32_t lsdaIndexArraySectionOffset; // section offset to start of lsda_index array for this range
  387. };
  388. struct unwind_info_section_header_lsda_index_entry
  389. {
  390. uint32_t functionOffset;
  391. uint32_t lsdaOffset;
  392. };
  393. //
  394. // There are two kinds of second level index pages: regular and compressed.
  395. // A compressed page can hold up to 1021 entries, but it cannot be used
  396. // if too many different encoding types are used. The regular page holds
  397. // 511 entries.
  398. //
  399. struct unwind_info_regular_second_level_entry
  400. {
  401. uint32_t functionOffset;
  402. compact_unwind_encoding_t encoding;
  403. };
  404. #define UNWIND_SECOND_LEVEL_REGULAR 2
  405. struct unwind_info_regular_second_level_page_header
  406. {
  407. uint32_t kind; // UNWIND_SECOND_LEVEL_REGULAR
  408. uint16_t entryPageOffset;
  409. uint16_t entryCount;
  410. // entry array
  411. };
  412. #define UNWIND_SECOND_LEVEL_COMPRESSED 3
  413. struct unwind_info_compressed_second_level_page_header
  414. {
  415. uint32_t kind; // UNWIND_SECOND_LEVEL_COMPRESSED
  416. uint16_t entryPageOffset;
  417. uint16_t entryCount;
  418. uint16_t encodingsPageOffset;
  419. uint16_t encodingsCount;
  420. // 32-bit entry array
  421. // encodings array
  422. };
  423. #define UNWIND_INFO_COMPRESSED_ENTRY_FUNC_OFFSET(entry) (entry & 0x00FFFFFF)
  424. #define UNWIND_INFO_COMPRESSED_ENTRY_ENCODING_INDEX(entry) ((entry >> 24) & 0xFF)
  425. #endif