/* 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 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(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 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_