airs-notes/eh_frame.md

# .eh_frame

When gcc generates code that handles exceptions, it produces tables that
describe how to unwind the stack. These tables are found in the `.eh_frame`
section. The format of the `.eh_frame` section is very similar to the format of
a DWARF `.debug_frame` section. Unfortunately, it is not precisely identical. I
don’t know of any documentation which describes this format. The following
should be read in conjunction with the relevant section of the DWARF standard,
available from http://dwarfstd.org.

The `.eh_frame` section is a sequence of records. Each record is either a CIE
(Common Information Entry) or an FDE (Frame Description Entry). In general
there is one CIE per object file, and each CIE is associated with a list of
FDEs. Each FDE is typically associated with a single function. The CIE and the
FDE together describe how to unwind to the caller if the current instruction
pointer is in the range covered by the FDE.

There should be exactly one FDE covering each instruction which may be being
executed when an exception occurs. By default an exception can only occur
during a function call or a throw. When using the `-fnon-call-exceptions` gcc
option, an exception can also occur on most memory references and floating
point operations. When using `-fasynchronous-unwind-tables`, the FDE will cover
every instruction, to permit unwinding from a signal handler.

The general format of a CIE or FDE starts as follows:

* Length of record. Read 4 bytes. If they are not `0xffffffff`, they are the
  length of the CIE or FDE record. Otherwise the next 64 bits holds the length,
  and this is a 64-bit DWARF format. This is like `.debug_frame`.
* A 4 byte ID. For a CIE this is 0. For an FDE it is the byte offset from this
  field to the start of the CIE with which this FDE is associated. The byte
  offset goes to the length record of the CIE. A positive value goes backward;
  that is, you have to subtract the value of the ID field from the current byte
  position to get the CIE position. This differs from `.debug_frame` in that
  the offset is relative rather than being an offset into the `.debug_frame`
  section.

A CIE record continues as follows:

* 1 byte CIE version. As of this writing this should be 1 or 3.
* NUL terminated augmentation string. This is a sequence of characters. Very
  old versions of gcc used the string “eh” here, but I won’t document that.
  This is described further below.
* Code alignment factor, an unsigned LEB128 (LEB128 is a DWARF encoding for
  numbers which I won’t describe here). This should always be 1 for `.eh_frame`.
* Data alignment factor, a signed LEB128. This is a constant factored out of
  offset instructions, as in `.debug_frame`.
* The return address register. In CIE version 1 this is a single byte; in CIE
  version 3 this is an unsigned LEB128. This indicates which column in the
  frame table represents the return address.

The next fields of the CIE depend on the augmentation string.

* If the augmentation string starts with ‘z’, we now find an unsigned LEB128
  which is the length of the augmentation data, rounded up so that the CIE ends
  on an address boundary. This is used to skip to the end of the augmentation
  data if an unrecognized augmentation character is seen.
* If the next character in the augmentation string is ‘L’, the next byte in the
  CIE is the LSDA (Language Specific Data Area) encoding. This is a
  `DW_EH_PE_xxx` value (described later). The default is `DW_EH_PE_absptr`.
* If the next character in the augmentation string is ‘R’, the next byte in the
  CIE is the FDE encoding. This is a `DW_EH_PE_xxx` value. The default is
  `DW_EH_PE_absptr`.
* The character ‘S’ in the augmentation string means that this CIE represents a
  stack frame for the invocation of a signal handler. When unwinding the stack,
  signal stack frames are handled slightly differently: the instruction pointer
  is assumed to be before the next instruction to execute rather than after it.
* If the next character in the augmentation string is ‘P’, the next byte in the
  CIE is the personality encoding, a `DW_EH_PE_xxx` value. This is followed by
  a pointer to the personality function, encoded using the personality
  encoding.  I’ll describe the personality function some other day.

The remaining bytes are an array of `DW_CFA_xxx` opcodes which define the
initial values for the frame table. This is then followed by `DW_CFA_nop`
padding bytes as required to match the total length of the CIE.

An FDE starts with the length and ID described above, and then continues as
follows.

* The starting address to which this FDE applies. This is encoded using the FDE
  encoding specified by the associated CIE.
* The number of bytes after the start address to which this FDE applies. This
  is encoded using the FDE encoding.
* If the CIE augmentation string starts with ‘z’, the FDE next has an unsigned
  LEB128 which is the total size of the FDE augmentation data. This may be used
  to skip data associated with unrecognized augmentation characters.
* If the CIE does not specify `DW_EH_PE_omit` as the LSDA encoding, the FDE
  next has a pointer to the LSDA, encoded as specified by the CIE.

The remaining bytes in the FDE are an array of `DW_CFA_xxx` opcodes which set
values in the frame table for unwinding to the caller.

The `DW_EH_PE_xxx` encodings describe how to encode values in a CIE or FDE. The
basic encoding is as follows:

* `DW_EH_PE_absptr = 0x00`: An absolute pointer. The size is determined by
  whether this is a 32-bit or 64-bit address space, and will be 32 or 64 bits.
* `DW_EH_PE_omit = 0xff`: The value is omitted.
* `DW_EH_PE_uleb128 = 0x01`: The value is an unsigned LEB128.
* `DW_EH_PE_udata2 = 0x02`, `DW_EH_PE_udata4 = 0x03`, `DW_EH_PE_udata8 = 0x04`:
  The value is stored as unsigned data with the specified number of bytes.
* `DW_EH_PE_signed = 0x08`: A signed number. The size is determined by whether
  this is a 32-bit or 64-bit address space. I don’t think this ever appears in
  a CIE or FDE in practice.
* `DW_EH_PE_sleb128 = 0x09`: A signed LEB128. Not used in practice.
* `DW_EH_PE_sdata2 = 0x0a`, `DW_EH_PE_sdata4 = 0x0b`, `DW_EH_PE_sdata8 = 0x0c`:
  The value is stored as signed data with the specified number of bytes. Not
  used in practice.

In addition the above basic encodings, there are modifiers.

* `DW_EH_PE_pcrel = 0x10`: Value is PC relative.
* `DW_EH_PE_textrel = 0x20`: Value is text relative.
* `DW_EH_PE_datarel = 0x30`: Value is data relative.
* `DW_EH_PE_funcrel = 0x40`: Value is relative to start of function.
* `DW_EH_PE_aligned = 0x50`: Value is aligned: padding bytes are inserted as
  required to make value be naturally aligned.
* `DW_EH_PE_indirect = 0x80`: This is actually the address of the real value.

If you follow all that, and also read up on `.debug_frame`, then you have
enough information to unwind the stack at runtime, e.g. to implement glibc’s
backtrace function. Later I’ll describe the LSDA and the personality function,
which work together to implement exception catching on top of stack unwinding.