/thirdparty/breakpad/common/dwarf/cfi_assembler.h

  1// -*- mode: C++ -*-
  2
  3// Copyright (c) 2010, Google Inc.
  4// All rights reserved.
  5//
  6// Redistribution and use in source and binary forms, with or without
  7// modification, are permitted provided that the following conditions are
  8// met:
  9//
 10//     * Redistributions of source code must retain the above copyright
 11// notice, this list of conditions and the following disclaimer.
 12//     * Redistributions in binary form must reproduce the above
 13// copyright notice, this list of conditions and the following disclaimer
 14// in the documentation and/or other materials provided with the
 15// distribution.
 16//     * Neither the name of Google Inc. nor the names of its
 17// contributors may be used to endorse or promote products derived from
 18// this software without specific prior written permission.
 19//
 20// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 21// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 22// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 23// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 24// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 25// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 26// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 27// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 28// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 29// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 30// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 31
 32// Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
 33
 34// cfi_assembler.h: Define CFISection, a class for creating properly
 35// (and improperly) formatted DWARF CFI data for unit tests.
 36
 37#ifndef PROCESSOR_CFI_ASSEMBLER_H_
 38#define PROCESSOR_CFI_ASSEMBLER_H_
 39
 40#include <string>
 41
 42#include "common/dwarf/dwarf2enums.h"
 43#include "common/test_assembler.h"
 44#include "google_breakpad/common/breakpad_types.h"
 45
 46namespace google_breakpad {
 47
 48using dwarf2reader::DwarfPointerEncoding;
 49using google_breakpad::test_assembler::Endianness;
 50using google_breakpad::test_assembler::Label;
 51using google_breakpad::test_assembler::Section;
 52using std::string;
 53
 54class CFISection: public Section {
 55 public:
 56
 57  // CFI augmentation strings beginning with 'z', defined by the
 58  // Linux/IA-64 C++ ABI, can specify interesting encodings for
 59  // addresses appearing in FDE headers and call frame instructions (and
 60  // for additional fields whose presence the augmentation string
 61  // specifies). In particular, pointers can be specified to be relative
 62  // to various base address: the start of the .text section, the
 63  // location holding the address itself, and so on. These allow the
 64  // frame data to be position-independent even when they live in
 65  // write-protected pages. These variants are specified at the
 66  // following two URLs:
 67  //
 68  // http://refspecs.linux-foundation.org/LSB_4.0.0/LSB-Core-generic/LSB-Core-generic/dwarfext.html
 69  // http://refspecs.linux-foundation.org/LSB_4.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html
 70  //
 71  // CFISection leaves the production of well-formed 'z'-augmented CIEs and
 72  // FDEs to the user, but does provide EncodedPointer, to emit
 73  // properly-encoded addresses for a given pointer encoding.
 74  // EncodedPointer uses an instance of this structure to find the base
 75  // addresses it should use; you can establish a default for all encoded
 76  // pointers appended to this section with SetEncodedPointerBases.
 77  struct EncodedPointerBases {
 78    EncodedPointerBases() : cfi(), text(), data() { }
 79
 80    // The starting address of this CFI section in memory, for
 81    // DW_EH_PE_pcrel. DW_EH_PE_pcrel pointers may only be used in data
 82    // that has is loaded into the program's address space.
 83    u_int64_t cfi;
 84
 85    // The starting address of this file's .text section, for DW_EH_PE_textrel.
 86    u_int64_t text;
 87
 88    // The starting address of this file's .got or .eh_frame_hdr section,
 89    // for DW_EH_PE_datarel.
 90    u_int64_t data;
 91  };
 92
 93  // Create a CFISection whose endianness is ENDIANNESS, and where
 94  // machine addresses are ADDRESS_SIZE bytes long. If EH_FRAME is
 95  // true, use the .eh_frame format, as described by the Linux
 96  // Standards Base Core Specification, instead of the DWARF CFI
 97  // format.
 98  CFISection(Endianness endianness, size_t address_size,
 99             bool eh_frame = false)
100      : Section(endianness), address_size_(address_size), eh_frame_(eh_frame),
101        pointer_encoding_(dwarf2reader::DW_EH_PE_absptr),
102        encoded_pointer_bases_(), entry_length_(NULL), in_fde_(false) {
103    // The 'start', 'Here', and 'Mark' members of a CFISection all refer
104    // to section offsets.
105    start() = 0;
106  }
107
108  // Return this CFISection's address size.
109  size_t AddressSize() const { return address_size_; }
110
111  // Return true if this CFISection uses the .eh_frame format, or
112  // false if it contains ordinary DWARF CFI data.
113  bool ContainsEHFrame() const { return eh_frame_; }
114
115  // Use ENCODING for pointers in calls to FDEHeader and EncodedPointer.
116  void SetPointerEncoding(DwarfPointerEncoding encoding) {
117    pointer_encoding_ = encoding;
118  }
119
120  // Use the addresses in BASES as the base addresses for encoded
121  // pointers in subsequent calls to FDEHeader or EncodedPointer.
122  // This function makes a copy of BASES.
123  void SetEncodedPointerBases(const EncodedPointerBases &bases) {
124    encoded_pointer_bases_ = bases;
125  }
126
127  // Append a Common Information Entry header to this section with the
128  // given values. If dwarf64 is true, use the 64-bit DWARF initial
129  // length format for the CIE's initial length. Return a reference to
130  // this section. You should call FinishEntry after writing the last
131  // instruction for the CIE.
132  //
133  // Before calling this function, you will typically want to use Mark
134  // or Here to make a label to pass to FDEHeader that refers to this
135  // CIE's position in the section.
136  CFISection &CIEHeader(u_int64_t code_alignment_factor,
137                        int data_alignment_factor,
138                        unsigned return_address_register,
139                        u_int8_t version = 3,
140                        const string &augmentation = "",
141                        bool dwarf64 = false);
142
143  // Append a Frame Description Entry header to this section with the
144  // given values. If dwarf64 is true, use the 64-bit DWARF initial
145  // length format for the CIE's initial length. Return a reference to
146  // this section. You should call FinishEntry after writing the last
147  // instruction for the CIE.
148  //
149  // This function doesn't support entries that are longer than
150  // 0xffffff00 bytes. (The "initial length" is always a 32-bit
151  // value.) Nor does it support .debug_frame sections longer than
152  // 0xffffff00 bytes.
153  CFISection &FDEHeader(Label cie_pointer,
154                        u_int64_t initial_location,
155                        u_int64_t address_range,
156                        bool dwarf64 = false);
157
158  // Note the current position as the end of the last CIE or FDE we
159  // started, after padding with DW_CFA_nops for alignment. This
160  // defines the label representing the entry's length, cited in the
161  // entry's header. Return a reference to this section.
162  CFISection &FinishEntry();
163
164  // Append the contents of BLOCK as a DW_FORM_block value: an
165  // unsigned LEB128 length, followed by that many bytes of data.
166  CFISection &Block(const string &block) {
167    ULEB128(block.size());
168    Append(block);
169    return *this;
170  }
171
172  // Append ADDRESS to this section, in the appropriate size and
173  // endianness. Return a reference to this section.
174  CFISection &Address(u_int64_t address) {
175    Section::Append(endianness(), address_size_, address);
176    return *this;
177  }
178  CFISection &Address(Label address) {
179    Section::Append(endianness(), address_size_, address);
180    return *this;
181  }
182
183  // Append ADDRESS to this section, using ENCODING and BASES. ENCODING
184  // defaults to this section's default encoding, established by
185  // SetPointerEncoding. BASES defaults to this section's bases, set by
186  // SetEncodedPointerBases. If the DW_EH_PE_indirect bit is set in the
187  // encoding, assume that ADDRESS is where the true address is stored.
188  // Return a reference to this section.
189  // 
190  // (C++ doesn't let me use default arguments here, because I want to
191  // refer to members of *this in the default argument expression.)
192  CFISection &EncodedPointer(u_int64_t address) {
193    return EncodedPointer(address, pointer_encoding_, encoded_pointer_bases_);
194  }
195  CFISection &EncodedPointer(u_int64_t address, DwarfPointerEncoding encoding) {
196    return EncodedPointer(address, encoding, encoded_pointer_bases_);
197  }
198  CFISection &EncodedPointer(u_int64_t address, DwarfPointerEncoding encoding,
199                             const EncodedPointerBases &bases);
200
201  // Restate some member functions, to keep chaining working nicely.
202  CFISection &Mark(Label *label)   { Section::Mark(label); return *this; }
203  CFISection &D8(u_int8_t v)       { Section::D8(v);       return *this; }
204  CFISection &D16(u_int16_t v)     { Section::D16(v);      return *this; }
205  CFISection &D16(Label v)         { Section::D16(v);      return *this; }
206  CFISection &D32(u_int32_t v)     { Section::D32(v);      return *this; }
207  CFISection &D32(const Label &v)  { Section::D32(v);      return *this; }
208  CFISection &D64(u_int64_t v)     { Section::D64(v);      return *this; }
209  CFISection &D64(const Label &v)  { Section::D64(v);      return *this; }
210  CFISection &LEB128(long long v)  { Section::LEB128(v);   return *this; }
211  CFISection &ULEB128(u_int64_t v) { Section::ULEB128(v);  return *this; }
212
213 private:
214  // A length value that we've appended to the section, but is not yet
215  // known. LENGTH is the appended value; START is a label referring
216  // to the start of the data whose length was cited.
217  struct PendingLength {
218    Label length;
219    Label start;
220  };
221
222  // Constants used in CFI/.eh_frame data:
223
224  // If the first four bytes of an "initial length" are this constant, then
225  // the data uses the 64-bit DWARF format, and the length itself is the
226  // subsequent eight bytes.
227  static const u_int32_t kDwarf64InitialLengthMarker = 0xffffffffU;
228
229  // The CIE identifier for 32- and 64-bit DWARF CFI and .eh_frame data.
230  static const u_int32_t kDwarf32CIEIdentifier = ~(u_int32_t)0;
231  static const u_int64_t kDwarf64CIEIdentifier = ~(u_int64_t)0;
232  static const u_int32_t kEHFrame32CIEIdentifier = 0;
233  static const u_int64_t kEHFrame64CIEIdentifier = 0;
234
235  // The size of a machine address for the data in this section.
236  size_t address_size_;
237
238  // If true, we are generating a Linux .eh_frame section, instead of
239  // a standard DWARF .debug_frame section.
240  bool eh_frame_;
241
242  // The encoding to use for FDE pointers.
243  DwarfPointerEncoding pointer_encoding_;
244
245  // The base addresses to use when emitting encoded pointers.
246  EncodedPointerBases encoded_pointer_bases_;
247
248  // The length value for the current entry.
249  //
250  // Oddly, this must be dynamically allocated. Labels never get new
251  // values; they only acquire constraints on the value they already
252  // have, or assert if you assign them something incompatible. So
253  // each header needs truly fresh Label objects to cite in their
254  // headers and track their positions. The alternative is explicit
255  // destructor invocation and a placement new. Ick.
256  PendingLength *entry_length_;
257
258  // True if we are currently emitting an FDE --- that is, we have
259  // called FDEHeader but have not yet called FinishEntry.
260  bool in_fde_;
261
262  // If in_fde_ is true, this is its starting address. We use this for
263  // emitting DW_EH_PE_funcrel pointers.
264  u_int64_t fde_start_address_;
265};
266
267}  // namespace google_breakpad
268
269#endif  // PROCESSOR_CFI_ASSEMBLER_H_