hphp/util/eh-frame.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef HPHP_UTIL_EH_FRAME_H_
  18 #define HPHP_UTIL_EH_FRAME_H_
  19
  20 #include "hphp/util/data-block.h"
  21 #include "hphp/util/dwarf-reg.h"
  22
  23 #include <boost/mpl/identity.hpp>
  24 #include <folly/Memory.h>
  25
  26 #include <cstring>
  27 #include <memory>
  28 #include <utility>
  29 #include <vector>
  30
  31 #ifndef _MSC_VER
  32 #include <dwarf.h>
  33 #include <libdwarf.h>
  34 #else
  35 #include "hphp/util/eh-frame-msvc.h"
  36 #endif
  37
  38 namespace HPHP {
  39
  40 ///////////////////////////////////////////////////////////////////////////////
  41
  42 /*
  43  * A handle to a dynamically-generated .eh_frame section.
  44  *
  45  * Contains an exclusive pointer to a buffer, as well as routines for
  46  * inspecting its contents.  When destructed, it deregisters the .eh_frame
  47  * sections and frees the buffer.
  48  */
  49 struct EHFrameDesc {
  50   ~EHFrameDesc();
  51
  52   EHFrameDesc() {}
  53   EHFrameDesc(EHFrameDesc&&) = default;
  54
  55   /*
  56    * Shared component (the "header") of CIEs and FDEs.
  57    */
  58   struct Entry {
  59     const uint8_t* get() const;
  60     uint32_t length() const;
  61     uint32_t cie_off() const;
  62
  63     Entry(const std::vector<uint8_t>& vec, size_t idx)
  64       : m_vec(vec)
  65       , m_idx(idx)
  66     {}
  67     const std::vector<uint8_t>& m_vec;
  68     size_t m_idx;
  69   };
  70
  71   /*
  72    * Helper structs for reading CIE and FDE data.
  73    */
  74   struct CIE : Entry {
  75     private: using Entry::Entry;
  76   };
  77   struct FDE : Entry {
  78     CodeAddress start() const;
  79     size_t range() const;
  80
  81     private: using Entry::Entry;
  82   };
  83
  84   CIE cie() const;
  85
  86   template<class F>
  87   void for_each_fde(F f) const;
  88
  89 private:
  90   friend struct EHFrameWriter;
  91   std::unique_ptr<std::vector<uint8_t>> m_buf;
  92 };
  93
  94 /*
  95  * API for dynamically creating and registering new .eh_frame sections.
  96  *
  97  * An EHFrameWriter instance can be given (or asked to create) an exclusive
  98  * pointer to a buffer.  It permits writing exactly one CIE, contiguously
  99  * followed by any number of FDES, before registering any FDEs written and
 100  * returning an EHFrameDesc---which, when destructed, deregisters and frees its
 101  * contents.
 102  *
 103  * In a pinch, EHFrameWriter could also just be used to write DWARF call frame
 104  * instructions to a buffer, without the .eh_frame specifics, though there are
 105  * currently assertions preventing that.
 106  */
 107 struct EHFrameWriter {
 108   /*
 109    * Constructors.
 110    *
 111    * Either allocate a fresh buffer, or take exclusive ownership of the
 112    * provided `buf'.
 113    */
 114   EHFrameWriter()
 115     : m_buf(std::make_unique<std::vector<uint8_t>>())
 116   {}
 117   explicit EHFrameWriter(std::unique_ptr<std::vector<uint8_t>>&& buf)
 118     : m_buf(std::move(buf))
 119   {}
 120
 121   /*
 122    * Register the FDE written to the buffer (if one was written), then release
 123    * the buffer.
 124    *
 125    * When all references to the returned value are lost, the buffer will delete
 126    * itself and deregister its FDE (if it exists).
 127    */
 128   EHFrameDesc register_and_release();
 129
 130   /////////////////////////////////////////////////////////////////////////////
 131
 132   /*
 133    * Write a CIE with the following fields:
 134    *
 135    *  length:       automatic
 136    *  CIE id:       0
 137    *  version:      1
 138    *  augment str:  personality ? "zPR" : "zR"
 139    *  code align:   1
 140    *  data align:   -8
 141    *  return reg:   rip
 142    *  augmentation: all pointer encodings DW_EH_PE_absptr
 143    *
 144    * Any initial call frame instructions should be written between the calls to
 145    * begin_cie() and end_cie().
 146    *
 147    * @see: https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/ehframechpt.html
 148    *       https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA.junk/dwarfext.html
 149    */
 150   void begin_cie(uint8_t rip, const void* personality = nullptr);
 151   void end_cie();
 152
 153   /*
 154    * Write an FDE with the following fields:
 155    *
 156    *  length:         automatic
 157    *  CIE pointer:    offset of `&m_buf[m_cie.idx]'
 158    *  initial PC:     `start'
 159    *  address range:  `size'
 160    *  augmentation:   0
 161    *
 162    * Any call frame instructions should be written between the calls to
 163    * begin_fde() and end_fde().
 164    */
 165   void begin_fde(CodeAddress start);
 166   void end_fde(size_t size);
 167
 168   /*
 169    * Write an FDE with zero length.
 170    *
 171    * This is required at the end of an .eh_frame section, to indicate that
 172    * there are no more FDEs sharing their CIE.  (This requirement does not
 173    * appear to be documented, but failing to zero-terminate causes a segfault
 174    * in classify_object_over_fdes() in unwind-dw2-fde.c.
 175    */
 176   void null_fde();
 177
 178   /////////////////////////////////////////////////////////////////////////////
 179   /*
 180    * Write a DWARF call frame instruction to the buffer.
 181    *
 182    * These all emit DW_CFA opcodes with the appropriate arguments.  For
 183    * documentation, see Chapter 6.4.2: Call Frame Instructions in
 184    * http://dwarfstd.org/doc/DWARF4.pdf
 185    */
 186
 187   /*
 188    * Row creation instruction.
 189    *
 190    * Emit the appropriate advance_loc* instruction, or set_loc if we are
 191    * advancing more than 2^32 bytes.
 192    */
 193   void advance_loc_to(CodeAddress addr);
 194
 195   /*
 196    * CFA definition instructions.
 197    */
 198   void def_cfa(uint8_t reg, uint64_t off);
 199   void def_cfa_register(uint8_t reg);
 200   void def_cfa_offset(uint64_t off);
 201   /*
 202    * Adjust the tracked CFA offset, and emit a def_cfa_offset for the new one.
 203    */
 204   void advance_cfa_offset(int64_t off);
 205
 206   /*
 207    * Register rule instructions.
 208    */
 209   void same_value(uint8_t reg);
 210   void offset(uint8_t reg, uint64_t off);
 211   void offset_extended_sf(uint8_t reg, int64_t off);
 212   void restore(uint8_t reg);
 213   /*
 214    * Begin a DWARF expression which either:
 215    * - expression():     computes the memory location which contains the value
 216    *                     of `reg'; or
 217    * - val_expression(): computes the value of `reg'.
 218    *
 219    * The operations comprising the expression should be written between the
 220    * calls to begin_{,val_}expression() and end_expression() (which ends either
 221    * kind of expression).
 222    *
 223    * At present, we always use DW_FORM_block1, and attempting to write an
 224    * expression whose operations contain more than (2^8 - 1) bytes will fail an
 225    * assertion.
 226    */
 227   void begin_expression(uint8_t reg);
 228   void begin_val_expression(uint8_t reg);
 229   void end_expression();
 230
 231   /*
 232    * Padding instruction.
 233    */
 234   void nop();
 235
 236   /////////////////////////////////////////////////////////////////////////////
 237   /*
 238    * Write a DWARF operation to the buffer.
 239    *
 240    * These all emit DW_OP opcodes with the appropriate arguments.  For
 241    * documentation, see Chapter 2.5: DWARF Expressions
 242    * http://dwarfstd.org/doc/DWARF4.pdf
 243    */
 244
 245   /*
 246    * Literal encodings.
 247    */
 248   void op_consts(int64_t cns);
 249
 250   /*
 251    * Register based addressing.
 252    */
 253   void op_breg(uint8_t reg, int64_t off);
 254
 255   /*
 256    * Stack operations.
 257    */
 258   void op_dup();
 259   void op_drop();
 260   void op_swap();
 261   void op_deref();
 262
 263   /*
 264    * Arithmetic and logical operations.
 265    */
 266   void op_abs();
 267   void op_and();
 268   void op_div();
 269   void op_minus();
 270   void op_mod();
 271   void op_mul();
 272   void op_neg();
 273   void op_not();
 274   void op_or();
 275   void op_plus();
 276
 277
 278   /////////////////////////////////////////////////////////////////////////////
 279
 280 private:
 281   template<class T>
 282   void write(// Prevent template argument deduction:
 283              typename boost::mpl::identity<T>::type t) {
 284     auto& v = *m_buf;
 285     auto const idx = v.size();
 286     v.resize(idx + sizeof(T));
 287     auto caddr = &v[idx];
 288     std::memcpy(caddr, &t, sizeof t);
 289   }
 290
 291   void dw_cfa(uint8_t);
 292   void dw_op(uint8_t);
 293   void write_uleb(uint64_t);
 294   void write_sleb(int64_t);
 295
 296   void begin_expr_impl(uint8_t op, uint8_t reg);
 297
 298   static constexpr size_t kInvalidIdx = -1ull;
 299
 300   /////////////////////////////////////////////////////////////////////////////
 301
 302 private:
 303   // The managed buffer.
 304   std::unique_ptr<std::vector<uint8_t>> m_buf{nullptr};
 305
 306   // Metadata for the emitted CIE.
 307   struct {
 308     // Index of the CIE in m_buf.
 309     size_t idx{kInvalidIdx};
 310     // The CIE's data_alignment_factor.
 311     int64_t data_align{-8};
 312     // CFA offset at the end of the CIE's call frame instructions.
 313     uint64_t offset{0};
 314   } m_cie;
 315
 316   // Index in m_buf of the FDE currently being written.
 317   size_t m_fde{kInvalidIdx};
 318   // Current CFI table row address.
 319   CodeAddress m_loc{nullptr};
 320   // Current CFA offset.
 321   uint64_t m_off{0};
 322
 323   // Index in m_buf of the expression currently being written.
 324   size_t m_expr{kInvalidIdx};
 325 };
 326
 327 ///////////////////////////////////////////////////////////////////////////////
 328
 329 }
 330
 331 #include "hphp/util/eh-frame-inl.h"
 332
 333 #endif