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