sources/host-tools/ndk-stack/elff/dwarf_cu.h - platform/ndk - Git at Google

 /* Copyright (C) 2007-2010 The Android Open Source Project
 **
 ** This software is licensed under the terms of the GNU General Public
 ** License version 2, as published by the Free Software Foundation, and
 ** may be copied, distributed, and modified under those terms.
 **
 ** This program is distributed in the hope that it will be useful,
 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ** GNU General Public License for more details.
 */

 /*
  * Contains declaration of a class DwarfCU, that encapsulates a compilation
  * unit in the .debug_info section of the mapped ELF file.
  */

 #ifndef ELFF_DWARF_CU_H_
 #define ELFF_DWARF_CU_H_

 #include "dwarf_defs.h"
 #include "dwarf_die.h"

 /* Address information descriptor. */
 typedef struct Dwarf_AddressInfo {
   /* Routine DIE containing the address. */
   const DIEObject*  die_obj;

   /* Source file name for the address. */
   const char*       file_name;

   /* Source file directory path for the address. */
   const char*       dir_name;

   /* Source file line number for the address. */
   Elf_Word          line_number;
 } Dwarf_AddressInfo;

 /* STMTL header cached by compilation unit. This header is contained in
  * the .debug_line section of the ELF file. */
 typedef struct Dwarf_STMTL_Hdr {
   /* The size in bytes of the line number information for this compilation
    * unit, not including the unit_length field itself. */
   Elf_Xword                   unit_length;

   /* A version number. This number is specific to the line number information
    * and is independent of the DWARF version number. */
   Elf_Half                    version;

   /* The number of bytes following the header_length field to the beginning of
    * the first byte of the line number program itself. In the 32-bit DWARF
    * format, this is a 4-byte unsigned length; in the 64-bit DWARF format,
    * this field is an 8-byte unsigned length. */
   Elf_Xword                   header_length;

   /* The size in bytes of the smallest target machine instruction. Line number
    * program opcodes that alter the address register first multiply their
    * operands by this value. */
   Elf_Byte                    min_instruction_len;

   /* The initial value of the is_stmt register. */
   Elf_Byte                    default_is_stmt;

   /* This parameter affects the meaning of the special opcodes. */
   Elf_Sbyte                   line_base;

   /* This parameter affects the meaning of the special opcodes. */
   Elf_Byte                    line_range;

   /* The number assigned to the first special opcode. */
   Elf_Byte                    opcode_base;

   /* Points to standard_opcode_lengths array in the actual STMTL header in
    * the mapped .debug_line section. */
   const Elf_Byte*             standard_opcode_lengths;

   /* Pointer to the beginning of the list of include directories in the mapped
    * .debug_line section. */
   const char*                 include_directories;

   /* Number of include directories in the list that begins with
    * include_directories. */
   Elf_Word                    inc_dir_num;

   /* Pointer to the beginning of the list of file information in the mapped
    * .debug_line section. Each entry in this list begins with zero-terminated
    * file name, followed by ULEB128 encoding directory index for the file,
    * followed by ULEB128 encoding last modification time, followed by ULEB128
    * encoding length of file in bytes. */
   const Dwarf_STMTL_FileDesc* file_infos;

   /* Start of the "Line Number Program" in the mapped .debug_line section. */
   const Elf_Byte*             start;

   /* End of the "Line Number Program" in the mapped .debug_line section. */
   const Elf_Byte*             end;
 } Dwarf_STMTL_Hdr;

 /* Encapsulates architecture-independent functionality of a
  * compilation unit.
  */
 class DwarfCU : public DwarfAllocBase {
 friend class ElfFile;
  public:
   /* Constructs DwarfCU instance.
    * Param:
    *  elf - Instance of ElfFile containing this compilation unit.
    */
   explicit DwarfCU(ElfFile* elf);

   /* Destructs DwarfCU instance. */
   virtual ~DwarfCU();

   /* Creates DwarfCUImpl instance, depending on DWARF format.
    * Param:
    *  elf - Instance of ElfFile containing this compilation unit.
    *  hdr - Pointer to compilation unit header inside mapped .debug_info
    *    section of the ELF file. Actual data addressed by this pointer
    *    must be Dwarf32_CUHdr for 32 bit DWARFs, or Dwarf64_CUHdr for
    *    64 bit DWARFs.
    * Return:
    *  Created DwarfCUImpl instance (typecasted back to DwarfCU) on success,
    *  or NULL on failure.
    */
   static DwarfCU* create_instance(ElfFile* elf, const void* hdr);

   /* Process a DIE attribute.
    * Param:
    *  attr - Attribute list inside the mapped .debug_info section of the ELF
    *    file.
    *  form - Attribute's form, definig representation of attribute value in the
    *    mapped .debug_info section of the ELF file.
    *  attr_value - Upon return contains attribute value.
    * Return:
    *  Pointer to the next DIE attribute inside the mapped .debug_info section
    *  of the ELF file.
    */
   const Elf_Byte* process_attrib(const Elf_Byte* attr,
                                  Dwarf_Form form,
                                  Dwarf_Value* attr_value) const;

   /* Dumps this compilation unit to the stdout. */
   void dump() const;

   /* Gets instance of ElfFile containing this compilation unit. */
   ElfFile* elf_file() const {
     return elf_file_;
   }

   /* Gets DIE object for this CU. */
   DIEObject* cu_die() const {
     return cu_die_;
   }

   /* Gets byte size of the pointer type for this compilation unit. */
   Elf_Byte addr_sizeof() const {
     return addr_sizeof_;
   }

   /* Gets full path to the compilation directory (DW_AT_comp_dir attribute).
    * Return:
    *  Full path to the compilation directory (DW_AT_comp_dir attribute),
    *  or NULL, if that attribute was missing in CU's attribute list.
    */
   const char* comp_dir_path() const {
     DIEAttrib attr;
     return cu_die()->get_attrib(DW_AT_comp_dir, &attr) ? attr.value()->str :
                                                          NULL;
   }

   /* Gets relative (from the compilation directory) path to the compiled file.
    * (DW_AT_name attribute).
    * Return:
    *  Relative path to the compiled file (DW_AT_name attribute), or NULL, if
    *  that attribute was missing in CU's attribute list.
    */
   const char* rel_cu_path() const {
     DIEAttrib attr;
     return cu_die()->get_attrib(DW_AT_name, &attr) ? attr.value()->str :
                                                      NULL;
   }

   /* Gets next compilation unit in the list. NULL indicates the last CU. */
   DwarfCU* prev_cu() const {
     return prev_cu_;
   }

   /* Links this CU to the list of prevoiusly discovered CUs. */
   void set_prev_cu(DwarfCU* prev) {
     prev_cu_ = prev;
   }

   /* Checks if DWARF version for this CU is higher than 2. */
   bool is_DWARF3_or_higher() const {
     return version_ >= 3;
   }

   /* Gets DIE abbreviation for given abbreviation number.
    * See DwarfAbbrDieArray::get() */
   const Dwarf_Abbr_DIE* get_die_abbr(Dwarf_AbbrNum num) const {
     return abbrs_.get(num);
   }

   /* Gets DIE object containing given address.
    * DIE address ranges may overlap (for instance, address range for an inlined
    * routine will be contained within the address range of a routine where it
    * was inlined). This method will return a DIE object that is a "leaf" in
    * that inlining tree. I.e the returned DIE object represents the last DIE
    * in the branch of all DIEs containing given address.
    * Param:
    *  address - Address to get a DIE for. NOTE: for the sake of simplicity we
    *    explicitly use 64-bit type for an address.
    * Return:
    *  Leaf DIE containing given address, or NULL if this CU doesn't contain
    *  the given address.
    */
   DIEObject* get_leaf_die_for_address(Elf_Xword address) const {
     return cu_die_->get_leaf_for_address(address);
   }

   /* Checks if this CU contains 64, or 32-bit addresses. */
   bool is_CU_address_64() const {
     return addr_sizeof_ == 8;
   }
   bool is_CU_address_32() const {
     return addr_sizeof_ == 4;
   }

 //=============================================================================
 // DWARF format dependent methods
 //=============================================================================

  public:
   /* Parses this compilation unit in .debug_info section, collecting children
    * DIEs of this compilation unit.
    * Param:
    *  parse_context - Parsing context that lists tags for DIEs that should be
    *    collected during parsing. NULL passed in this parameter indicates DIEs
    *    for all tags should be collected.
    *  next_cu_die - Upon successful return contains pointer to the next
    *    compilation unit descriptor inside mapped .debug_info section of
    *    the ELF file.
    * Return:
    *  true on success, false on failure.
    */
   virtual bool parse(const DwarfParseContext* parse_context,
                      const void** next_cu_die) = 0;

   /* Gets a DIE object referenced by an offset from the beginning of
    * this CU in the mapped .debug_info section.
    */
   virtual DIEObject* get_referenced_die_object(Elf_Word ref) const = 0;

   /* Gets a reference to a DIE object (offset of the DIE from the
    * beginning of this CU in the mapped .debug_info section.
    */
   virtual Elf_Word get_die_reference(const Dwarf_DIE* die) const = 0;

   /* Gets PC address information.
    * Param:
    *  address - PC address to get information for.
    *  info - Upon success contains information about routine that belongs to
    *    this compilation unit, containing the given address.
    * Return:
    *  true on success, or false if this CU doesn't contain the given address.
    */
   virtual bool get_pc_address_file_info(Elf_Xword address,
                                         Dwarf_AddressInfo* info) = 0;

   /* Gets file descriptor in the mapped .debug_line section of ELF file for a
    * given index in the file descriptor list.
    * Param:
    *  index - 1-based index of file descriptor in the file descriptor list.
    * Return:
    *  File descriptor for the given index, or NULL if index was too big.
    *  NOTE: pointer returned from this method addressed mapped section of
    *  ELF file.
    */
   virtual const Dwarf_STMTL_FileDesc* get_stmt_file_info(Elf_Word index) = 0;

   /* Gets directory name by an index in the mapped .debug_line section of
    * ELF file.
    * Param:
    *  dir_index - Index of the directory in the file descriptor list. If this
    *    parameter is zero, compilation directory (DW_AT_comp_dir) for this CU
    *    will be returned.
    * Return:
    *  Directory name for the given index, or NULL if index was too big.
    *  NOTE: pointer returned from this method addressed mapped section of
    *  ELF file.
    */
   virtual const char* get_stmt_dir_name(Elf_Word dir_index) = 0;

  protected:
   /* DIE abbreviation descriptors, cached for this compilation unit. */
   DwarfAbbrDieArray   abbrs_;

   /* Instance of an ELF file that contains this compilation unit. */
   ElfFile*            elf_file_;

   /* DIE object for this CU. */
   DIEObject*          cu_die_;

   /* Next compilation unit in the list (previous in the order they've been
    * discovered during ELF file parsing).
    */
   DwarfCU*            prev_cu_;

   /* DWARF version for this CU. */
   Elf_Half            version_;

   /* Byte size of the pointer type for this compilation unit. */
   Elf_Byte            addr_sizeof_;
 };

 /* Encapsulates architecture-dependent functionality of a compilation unit.
  * Template param:
  *  Dwarf_CUHdr - type compilation unit header in the mapped .debug_info
  *    section of ELF file. Must be:
  *    - Dwarf32_CUHdr for 32-bit DWARF, or
  *    - Dwarf64_CUHdr for 64-bit DWARF.
  *  Dwarf_Off - type for an offset field in DWARF data format. Must be:
  *    - Dwarf32_Off for 32-bit DWARF, or
  *    - Dwarf64_Off for 64-bit DWARF.
  */
 template <typename Dwarf_CUHdr, typename Dwarf_Off>
 class DwarfCUImpl : public DwarfCU {
  public:
   /* Constructs DwarfCU instance.
    * Param:
    *  elf - Instance of ElfFile containing this compilation unit.
    *  hdr - Pointer to compilation unit header inside mapped .debug_info
    *    section of the ELF file.
    */
   DwarfCUImpl(ElfFile* elf, const Dwarf_CUHdr* hdr);

   /* Destructs DwarfCU instance. */
   ~DwarfCUImpl() {
   }

   /* Parses this compilation unit in .debug_info section, collecting children
    * DIEs of this compilation unit. This is an implementation of DwarfCU's
    * abstract metod.
    * See DwarfCU::parse().
    */
   bool parse(const DwarfParseContext* parse_context,
              const void** next_cu_die);

   /* Gets PC address information.
    * This is an implementation of DwarfCU's abstract metod.
    * See DwarfCU::get_pc_address_file_info().
    */
   bool get_pc_address_file_info(Elf_Xword address, Dwarf_AddressInfo* info);

   /* Gets file descriptor in the mapped .debug_line section of ELF file for a
    * given index in the file descriptor list.
    * This is an implementation of DwarfCU's abstract metod.
    * See DwarfCU::get_stmt_file_info().
    */
   const Dwarf_STMTL_FileDesc* get_stmt_file_info(Elf_Word index);

   /* Gets directory name by an index in the mapped .debug_line section of
    * ELF file.
    * This is an implementation of DwarfCU's abstract metod.
    * See DwarfCU::get_stmt_dir_name().
    */
   const char* get_stmt_dir_name(Elf_Word dir_index);

   /* Gets a DIE object referenced by an offset from the beginning of
    * this CU. This is an implementation of DwarfCU's abstract metod.
    */
   DIEObject* get_referenced_die_object(Elf_Word ref) const {
     const Dwarf_DIE* die = get_referenced_die(ref);
     return cu_die_->find_die_object(die);
   }

   /* Gets a reference to a DIE object (offset of the DIE from the
    * beginning of this CU in the mapped .debug_info section.
    * This is an implementation of DwarfCU's abstract metod.
    */
   Elf_Word get_die_reference(const Dwarf_DIE* die) const {
     return static_cast<Elf_Word>(diff_ptr(cu_header_, die));
   }

  protected:
   /* Process a child DIE (and all its children) in this compilation unit.
    * Param:
    *  parse_context - See DwarfCU::parse().
    *  die - DIE descriptor of the child to process in this method.
    *  parent_obj - Parent object of the child to process in this method.
    *    NOTE: this parameter can be NULL only for a DIE that represents this
    *    compilation unit itself.
    * Return:
    *  Pointer to the end of child's attribute list in the mapped .debug_info
    *  section on success, or NULL on failure. Usually, pointer returned from
    *  this method is simply discarded, since parent calculates address of the
    *  next sibling's DIE based on DW_AT_sibling attribute of the DIE preceding
    *  child's DIE.
    */
   const Elf_Byte* process_DIE(const DwarfParseContext* parse_context,
                               const Dwarf_DIE* die,
                               DIEObject* parent_obj);

   /* Creates a DIE object for the given DIE.
    * Param:
    *  parse_context See DwarfCU::parse().
    *  die - DIE to create an object for.
    *  parent - Parent DIE object for the one that's being created in this
    *    method.
    *  tag - Tag of the DIE object that's being created in this method.
    * Return:
    *  Created DIE object. This method may returns NULL in two cases:
    *    - We're not interested in this DIE (decided by looking at 'tag'
    *      parameter. In this case errno should be set to zero.
    *    - Memory allocation has failed. In this case errno should be
    *      set to ENOMEM.
    */
   DIEObject* create_die_object(const DwarfParseContext* parse_context,
                                const Dwarf_DIE* die,
                                DIEObject* parent,
                                Dwarf_Tag tag);

   /* Initializes (caches) STMT lines header for this CU. */
   bool init_stmtl();

   /* Saves current source file information, collected in the state machine by
    * the "Line Number Program".
    * Param:
    *  state - State machine collected "Line Number Program" results.
    *  info - Upon success contains source file information, copied over from
    *    the state machine.
    * Return:
    *  true on success, or false on failure.
    */
   bool set_source_info(const DwarfStateMachine* state,
                        Dwarf_AddressInfo* info);

   /* Gets pointer to the DIE descriptor for this CU. */
   const Dwarf_DIE* get_DIE() const {
     /* CU's DIE descriptor immediately follows CU header. */
     return INC_CPTR_T(Dwarf_DIE, cu_header_, sizeof(Dwarf_CUHdr));
   }

   /* Caches STMTL header from .debug_line section to stmtl_header_.
    * Template param:
    *  Dwarf_STMTL_Hdr - Dwarf_STMTL_Hdr32, or Dwarf_STMTL_Hdr64, depending
    *    on the header type.
    * Param:
    *  stmtl_hdr - STMTL header in the mapped .debug_line section to cache.
    */
   template <typename Dwarf_STMTL_Hdr>
   void cache_stmtl(const Dwarf_STMTL_Hdr* stmtl_hdr) {
     stmtl_header_.unit_length = elf_file()->pull_val(stmtl_hdr->unit_length.size);
     stmtl_header_.version = elf_file()->pull_val(stmtl_hdr->version);
     stmtl_header_.header_length = elf_file()->pull_val(stmtl_hdr->header_length);
     stmtl_header_.min_instruction_len = stmtl_hdr->min_instruction_len;
     stmtl_header_.default_is_stmt = stmtl_hdr->default_is_stmt;
     stmtl_header_.line_base = stmtl_hdr->line_base;
     stmtl_header_.line_range = stmtl_hdr->line_range;
     stmtl_header_.opcode_base = stmtl_hdr->opcode_base;
     stmtl_header_.standard_opcode_lengths = &stmtl_hdr->standard_opcode_lengths;
     stmtl_header_.start = INC_CPTR_T(Elf_Byte, &stmtl_hdr->min_instruction_len,
                                      stmtl_header_.header_length);
     stmtl_header_.end = INC_CPTR_T(Elf_Byte, &stmtl_hdr->version,
                                    stmtl_header_.unit_length);
     stmtl_header_.include_directories =
         INC_CPTR_T(char, stmtl_header_.standard_opcode_lengths,
                    stmtl_header_.opcode_base - 1);
     const char* dir = stmtl_header_.include_directories;
     while (*dir != '\0') {
       dir += strlen(dir) + 1;
       stmtl_header_.inc_dir_num++;
     }
     stmtl_header_.file_infos = INC_CPTR_T(Dwarf_STMTL_FileDesc, dir, 1);
   }

   /* Gets a DIE referenced by an offset from the beginning of this CU
    * in the mapped .debug_info section.
    */
   const Dwarf_DIE* get_referenced_die(Elf_Word ref) const {
     return INC_CPTR_T(Dwarf_DIE, cu_header_, ref);
   }

   /* Checks if pointer to the DIE attribute is contained within the CU's area
    * of the mapped .debug_info section.
    * Param:
    *  ptr - Pointer to the DIE attribute to check.
    * Return:
    *  true, if pointer to the DIE attribute is contained within the CU's area
    *  of the mapped .debug_info section, or false if attribute pointer goes
    *  beyond CU's area of the mapped .debug_info section.
    */
   bool is_attrib_ptr_valid(const void* ptr) const {
     return diff_ptr(cu_header_, ptr) < cu_size_;
   }

  protected:
   /* Pointer to this compilation unit header inside the mapped .debug_info
    * section of the ELF file.
    */
   const Dwarf_CUHdr*          cu_header_;

   /* Size of this compilation unit area in the mapped .debug_info section.
    * This value has been cached off the CU header in order to avoid
    * endianness conversions.
    */
   Dwarf_Off                   cu_size_;

   /* STMT lines header, cached off mapped .debug_line section. */
   Dwarf_STMTL_Hdr             stmtl_header_;
 };

 #endif  // ELFF_DWARF_CU_H_
	/* Copyright (C) 2007-2010 The Android Open Source Project
	**
	** This software is licensed under the terms of the GNU General Public
	** License version 2, as published by the Free Software Foundation, and
	** may be copied, distributed, and modified under those terms.
	**
	** This program is distributed in the hope that it will be useful,
	** but WITHOUT ANY WARRANTY; without even the implied warranty of
	** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	** GNU General Public License for more details.
	*/

	/*
	* Contains declaration of a class DwarfCU, that encapsulates a compilation
	* unit in the .debug_info section of the mapped ELF file.
	*/

	#ifndef ELFF_DWARF_CU_H_
	#define ELFF_DWARF_CU_H_

	#include "dwarf_defs.h"
	#include "dwarf_die.h"

	/* Address information descriptor. */
	typedef struct Dwarf_AddressInfo {
	/* Routine DIE containing the address. */
	const DIEObject* die_obj;

	/* Source file name for the address. */
	const char* file_name;

	/* Source file directory path for the address. */
	const char* dir_name;

	/* Source file line number for the address. */
	Elf_Word line_number;
	} Dwarf_AddressInfo;

	/* STMTL header cached by compilation unit. This header is contained in
	* the .debug_line section of the ELF file. */
	typedef struct Dwarf_STMTL_Hdr {
	/* The size in bytes of the line number information for this compilation
	* unit, not including the unit_length field itself. */
	Elf_Xword unit_length;

	/* A version number. This number is specific to the line number information
	* and is independent of the DWARF version number. */
	Elf_Half version;

	/* The number of bytes following the header_length field to the beginning of
	* the first byte of the line number program itself. In the 32-bit DWARF
	* format, this is a 4-byte unsigned length; in the 64-bit DWARF format,
	* this field is an 8-byte unsigned length. */
	Elf_Xword header_length;

	/* The size in bytes of the smallest target machine instruction. Line number
	* program opcodes that alter the address register first multiply their
	* operands by this value. */
	Elf_Byte min_instruction_len;

	/* The initial value of the is_stmt register. */
	Elf_Byte default_is_stmt;

	/* This parameter affects the meaning of the special opcodes. */
	Elf_Sbyte line_base;

	/* This parameter affects the meaning of the special opcodes. */
	Elf_Byte line_range;

	/* The number assigned to the first special opcode. */
	Elf_Byte opcode_base;

	/* Points to standard_opcode_lengths array in the actual STMTL header in
	* the mapped .debug_line section. */
	const Elf_Byte* standard_opcode_lengths;

	/* Pointer to the beginning of the list of include directories in the mapped
	* .debug_line section. */
	const char* include_directories;

	/* Number of include directories in the list that begins with
	* include_directories. */
	Elf_Word inc_dir_num;

	/* Pointer to the beginning of the list of file information in the mapped
	* .debug_line section. Each entry in this list begins with zero-terminated
	* file name, followed by ULEB128 encoding directory index for the file,
	* followed by ULEB128 encoding last modification time, followed by ULEB128
	* encoding length of file in bytes. */
	const Dwarf_STMTL_FileDesc* file_infos;

	/* Start of the "Line Number Program" in the mapped .debug_line section. */
	const Elf_Byte* start;

	/* End of the "Line Number Program" in the mapped .debug_line section. */
	const Elf_Byte* end;
	} Dwarf_STMTL_Hdr;

	/* Encapsulates architecture-independent functionality of a
	* compilation unit.
	*/
	class DwarfCU : public DwarfAllocBase {
	friend class ElfFile;
	public:
	/* Constructs DwarfCU instance.
	* Param:
	* elf - Instance of ElfFile containing this compilation unit.
	*/
	explicit DwarfCU(ElfFile* elf);

	/* Destructs DwarfCU instance. */
	virtual ~DwarfCU();

	/* Creates DwarfCUImpl instance, depending on DWARF format.
	* Param:
	* elf - Instance of ElfFile containing this compilation unit.
	* hdr - Pointer to compilation unit header inside mapped .debug_info
	* section of the ELF file. Actual data addressed by this pointer
	* must be Dwarf32_CUHdr for 32 bit DWARFs, or Dwarf64_CUHdr for
	* 64 bit DWARFs.
	* Return:
	* Created DwarfCUImpl instance (typecasted back to DwarfCU) on success,
	* or NULL on failure.
	*/
	static DwarfCU* create_instance(ElfFile* elf, const void* hdr);

	/* Process a DIE attribute.
	* Param:
	* attr - Attribute list inside the mapped .debug_info section of the ELF
	* file.
	* form - Attribute's form, definig representation of attribute value in the
	* mapped .debug_info section of the ELF file.
	* attr_value - Upon return contains attribute value.
	* Return:
	* Pointer to the next DIE attribute inside the mapped .debug_info section
	* of the ELF file.
	*/
	const Elf_Byte* process_attrib(const Elf_Byte* attr,
	Dwarf_Form form,
	Dwarf_Value* attr_value) const;

	/* Dumps this compilation unit to the stdout. */
	void dump() const;

	/* Gets instance of ElfFile containing this compilation unit. */
	ElfFile* elf_file() const {
	return elf_file_;
	}

	/* Gets DIE object for this CU. */
	DIEObject* cu_die() const {
	return cu_die_;
	}

	/* Gets byte size of the pointer type for this compilation unit. */
	Elf_Byte addr_sizeof() const {
	return addr_sizeof_;
	}

	/* Gets full path to the compilation directory (DW_AT_comp_dir attribute).
	* Return:
	* Full path to the compilation directory (DW_AT_comp_dir attribute),
	* or NULL, if that attribute was missing in CU's attribute list.
	*/
	const char* comp_dir_path() const {
	DIEAttrib attr;
	return cu_die()->get_attrib(DW_AT_comp_dir, &attr) ? attr.value()->str :
	NULL;
	}

	/* Gets relative (from the compilation directory) path to the compiled file.
	* (DW_AT_name attribute).
	* Return:
	* Relative path to the compiled file (DW_AT_name attribute), or NULL, if
	* that attribute was missing in CU's attribute list.
	*/
	const char* rel_cu_path() const {
	DIEAttrib attr;
	return cu_die()->get_attrib(DW_AT_name, &attr) ? attr.value()->str :
	NULL;
	}

	/* Gets next compilation unit in the list. NULL indicates the last CU. */
	DwarfCU* prev_cu() const {
	return prev_cu_;
	}

	/* Links this CU to the list of prevoiusly discovered CUs. */
	void set_prev_cu(DwarfCU* prev) {
	prev_cu_ = prev;
	}

	/* Checks if DWARF version for this CU is higher than 2. */
	bool is_DWARF3_or_higher() const {
	return version_ >= 3;
	}

	/* Gets DIE abbreviation for given abbreviation number.
	* See DwarfAbbrDieArray::get() */
	const Dwarf_Abbr_DIE* get_die_abbr(Dwarf_AbbrNum num) const {
	return abbrs_.get(num);
	}

	/* Gets DIE object containing given address.
	* DIE address ranges may overlap (for instance, address range for an inlined
	* routine will be contained within the address range of a routine where it
	* was inlined). This method will return a DIE object that is a "leaf" in
	* that inlining tree. I.e the returned DIE object represents the last DIE
	* in the branch of all DIEs containing given address.
	* Param:
	* address - Address to get a DIE for. NOTE: for the sake of simplicity we
	* explicitly use 64-bit type for an address.
	* Return:
	* Leaf DIE containing given address, or NULL if this CU doesn't contain
	* the given address.
	*/
	DIEObject* get_leaf_die_for_address(Elf_Xword address) const {
	return cu_die_->get_leaf_for_address(address);
	}

	/* Checks if this CU contains 64, or 32-bit addresses. */
	bool is_CU_address_64() const {
	return addr_sizeof_ == 8;
	}
	bool is_CU_address_32() const {
	return addr_sizeof_ == 4;
	}

	//=============================================================================
	// DWARF format dependent methods
	//=============================================================================

	public:
	/* Parses this compilation unit in .debug_info section, collecting children
	* DIEs of this compilation unit.
	* Param:
	* parse_context - Parsing context that lists tags for DIEs that should be
	* collected during parsing. NULL passed in this parameter indicates DIEs
	* for all tags should be collected.
	* next_cu_die - Upon successful return contains pointer to the next
	* compilation unit descriptor inside mapped .debug_info section of
	* the ELF file.
	* Return:
	* true on success, false on failure.
	*/
	virtual bool parse(const DwarfParseContext* parse_context,
	const void** next_cu_die) = 0;

	/* Gets a DIE object referenced by an offset from the beginning of
	* this CU in the mapped .debug_info section.
	*/
	virtual DIEObject* get_referenced_die_object(Elf_Word ref) const = 0;

	/* Gets a reference to a DIE object (offset of the DIE from the
	* beginning of this CU in the mapped .debug_info section.
	*/
	virtual Elf_Word get_die_reference(const Dwarf_DIE* die) const = 0;

	/* Gets PC address information.
	* Param:
	* address - PC address to get information for.
	* info - Upon success contains information about routine that belongs to
	* this compilation unit, containing the given address.
	* Return:
	* true on success, or false if this CU doesn't contain the given address.
	*/
	virtual bool get_pc_address_file_info(Elf_Xword address,
	Dwarf_AddressInfo* info) = 0;

	/* Gets file descriptor in the mapped .debug_line section of ELF file for a
	* given index in the file descriptor list.
	* Param:
	* index - 1-based index of file descriptor in the file descriptor list.
	* Return:
	* File descriptor for the given index, or NULL if index was too big.
	* NOTE: pointer returned from this method addressed mapped section of
	* ELF file.
	*/
	virtual const Dwarf_STMTL_FileDesc* get_stmt_file_info(Elf_Word index) = 0;

	/* Gets directory name by an index in the mapped .debug_line section of
	* ELF file.
	* Param:
	* dir_index - Index of the directory in the file descriptor list. If this
	* parameter is zero, compilation directory (DW_AT_comp_dir) for this CU
	* will be returned.
	* Return:
	* Directory name for the given index, or NULL if index was too big.
	* NOTE: pointer returned from this method addressed mapped section of
	* ELF file.
	*/
	virtual const char* get_stmt_dir_name(Elf_Word dir_index) = 0;

	protected:
	/* DIE abbreviation descriptors, cached for this compilation unit. */
	DwarfAbbrDieArray abbrs_;

	/* Instance of an ELF file that contains this compilation unit. */
	ElfFile* elf_file_;

	/* DIE object for this CU. */
	DIEObject* cu_die_;

	/* Next compilation unit in the list (previous in the order they've been
	* discovered during ELF file parsing).
	*/
	DwarfCU* prev_cu_;

	/* DWARF version for this CU. */
	Elf_Half version_;

	/* Byte size of the pointer type for this compilation unit. */
	Elf_Byte addr_sizeof_;
	};

	/* Encapsulates architecture-dependent functionality of a compilation unit.
	* Template param:
	* Dwarf_CUHdr - type compilation unit header in the mapped .debug_info
	* section of ELF file. Must be:
	* - Dwarf32_CUHdr for 32-bit DWARF, or
	* - Dwarf64_CUHdr for 64-bit DWARF.
	* Dwarf_Off - type for an offset field in DWARF data format. Must be:
	* - Dwarf32_Off for 32-bit DWARF, or
	* - Dwarf64_Off for 64-bit DWARF.
	*/
	template <typename Dwarf_CUHdr, typename Dwarf_Off>
	class DwarfCUImpl : public DwarfCU {
	public:
	/* Constructs DwarfCU instance.
	* Param:
	* elf - Instance of ElfFile containing this compilation unit.
	* hdr - Pointer to compilation unit header inside mapped .debug_info
	* section of the ELF file.
	*/
	DwarfCUImpl(ElfFile* elf, const Dwarf_CUHdr* hdr);

	/* Destructs DwarfCU instance. */
	~DwarfCUImpl() {
	}

	/* Parses this compilation unit in .debug_info section, collecting children
	* DIEs of this compilation unit. This is an implementation of DwarfCU's
	* abstract metod.
	* See DwarfCU::parse().
	*/
	bool parse(const DwarfParseContext* parse_context,
	const void** next_cu_die);

	/* Gets PC address information.
	* This is an implementation of DwarfCU's abstract metod.
	* See DwarfCU::get_pc_address_file_info().
	*/
	bool get_pc_address_file_info(Elf_Xword address, Dwarf_AddressInfo* info);

	/* Gets file descriptor in the mapped .debug_line section of ELF file for a
	* given index in the file descriptor list.
	* This is an implementation of DwarfCU's abstract metod.
	* See DwarfCU::get_stmt_file_info().
	*/
	const Dwarf_STMTL_FileDesc* get_stmt_file_info(Elf_Word index);

	/* Gets directory name by an index in the mapped .debug_line section of
	* ELF file.
	* This is an implementation of DwarfCU's abstract metod.
	* See DwarfCU::get_stmt_dir_name().
	*/
	const char* get_stmt_dir_name(Elf_Word dir_index);

	/* Gets a DIE object referenced by an offset from the beginning of
	* this CU. This is an implementation of DwarfCU's abstract metod.
	*/
	DIEObject* get_referenced_die_object(Elf_Word ref) const {
	const Dwarf_DIE* die = get_referenced_die(ref);
	return cu_die_->find_die_object(die);
	}

	/* Gets a reference to a DIE object (offset of the DIE from the
	* beginning of this CU in the mapped .debug_info section.
	* This is an implementation of DwarfCU's abstract metod.
	*/
	Elf_Word get_die_reference(const Dwarf_DIE* die) const {
	return static_cast<Elf_Word>(diff_ptr(cu_header_, die));
	}

	protected:
	/* Process a child DIE (and all its children) in this compilation unit.
	* Param:
	* parse_context - See DwarfCU::parse().
	* die - DIE descriptor of the child to process in this method.
	* parent_obj - Parent object of the child to process in this method.
	* NOTE: this parameter can be NULL only for a DIE that represents this
	* compilation unit itself.
	* Return:
	* Pointer to the end of child's attribute list in the mapped .debug_info
	* section on success, or NULL on failure. Usually, pointer returned from
	* this method is simply discarded, since parent calculates address of the
	* next sibling's DIE based on DW_AT_sibling attribute of the DIE preceding
	* child's DIE.
	*/
	const Elf_Byte* process_DIE(const DwarfParseContext* parse_context,
	const Dwarf_DIE* die,
	DIEObject* parent_obj);

	/* Creates a DIE object for the given DIE.
	* Param:
	* parse_context See DwarfCU::parse().
	* die - DIE to create an object for.
	* parent - Parent DIE object for the one that's being created in this
	* method.
	* tag - Tag of the DIE object that's being created in this method.
	* Return:
	* Created DIE object. This method may returns NULL in two cases:
	* - We're not interested in this DIE (decided by looking at 'tag'
	* parameter. In this case errno should be set to zero.
	* - Memory allocation has failed. In this case errno should be
	* set to ENOMEM.
	*/
	DIEObject* create_die_object(const DwarfParseContext* parse_context,
	const Dwarf_DIE* die,
	DIEObject* parent,
	Dwarf_Tag tag);

	/* Initializes (caches) STMT lines header for this CU. */
	bool init_stmtl();

	/* Saves current source file information, collected in the state machine by
	* the "Line Number Program".
	* Param:
	* state - State machine collected "Line Number Program" results.
	* info - Upon success contains source file information, copied over from
	* the state machine.
	* Return:
	* true on success, or false on failure.
	*/
	bool set_source_info(const DwarfStateMachine* state,
	Dwarf_AddressInfo* info);

	/* Gets pointer to the DIE descriptor for this CU. */
	const Dwarf_DIE* get_DIE() const {
	/* CU's DIE descriptor immediately follows CU header. */
	return INC_CPTR_T(Dwarf_DIE, cu_header_, sizeof(Dwarf_CUHdr));
	}

	/* Caches STMTL header from .debug_line section to stmtl_header_.
	* Template param:
	* Dwarf_STMTL_Hdr - Dwarf_STMTL_Hdr32, or Dwarf_STMTL_Hdr64, depending
	* on the header type.
	* Param:
	* stmtl_hdr - STMTL header in the mapped .debug_line section to cache.
	*/
	template <typename Dwarf_STMTL_Hdr>
	void cache_stmtl(const Dwarf_STMTL_Hdr* stmtl_hdr) {
	stmtl_header_.unit_length = elf_file()->pull_val(stmtl_hdr->unit_length.size);
	stmtl_header_.version = elf_file()->pull_val(stmtl_hdr->version);
	stmtl_header_.header_length = elf_file()->pull_val(stmtl_hdr->header_length);
	stmtl_header_.min_instruction_len = stmtl_hdr->min_instruction_len;
	stmtl_header_.default_is_stmt = stmtl_hdr->default_is_stmt;
	stmtl_header_.line_base = stmtl_hdr->line_base;
	stmtl_header_.line_range = stmtl_hdr->line_range;
	stmtl_header_.opcode_base = stmtl_hdr->opcode_base;
	stmtl_header_.standard_opcode_lengths = &stmtl_hdr->standard_opcode_lengths;
	stmtl_header_.start = INC_CPTR_T(Elf_Byte, &stmtl_hdr->min_instruction_len,
	stmtl_header_.header_length);
	stmtl_header_.end = INC_CPTR_T(Elf_Byte, &stmtl_hdr->version,
	stmtl_header_.unit_length);
	stmtl_header_.include_directories =
	INC_CPTR_T(char, stmtl_header_.standard_opcode_lengths,
	stmtl_header_.opcode_base - 1);
	const char* dir = stmtl_header_.include_directories;
	while (*dir != '\0') {
	dir += strlen(dir) + 1;
	stmtl_header_.inc_dir_num++;
	}
	stmtl_header_.file_infos = INC_CPTR_T(Dwarf_STMTL_FileDesc, dir, 1);
	}

	/* Gets a DIE referenced by an offset from the beginning of this CU
	* in the mapped .debug_info section.
	*/
	const Dwarf_DIE* get_referenced_die(Elf_Word ref) const {
	return INC_CPTR_T(Dwarf_DIE, cu_header_, ref);
	}

	/* Checks if pointer to the DIE attribute is contained within the CU's area
	* of the mapped .debug_info section.
	* Param:
	* ptr - Pointer to the DIE attribute to check.
	* Return:
	* true, if pointer to the DIE attribute is contained within the CU's area
	* of the mapped .debug_info section, or false if attribute pointer goes
	* beyond CU's area of the mapped .debug_info section.
	*/
	bool is_attrib_ptr_valid(const void* ptr) const {
	return diff_ptr(cu_header_, ptr) < cu_size_;
	}

	protected:
	/* Pointer to this compilation unit header inside the mapped .debug_info
	* section of the ELF file.
	*/
	const Dwarf_CUHdr* cu_header_;

	/* Size of this compilation unit area in the mapped .debug_info section.
	* This value has been cached off the CU header in order to avoid
	* endianness conversions.
	*/
	Dwarf_Off cu_size_;

	/* STMT lines header, cached off mapped .debug_line section. */
	Dwarf_STMTL_Hdr stmtl_header_;
	};

	#endif // ELFF_DWARF_CU_H_