// Copyright (c) Meta Platforms, Inc. and affiliates. // SPDX-License-Identifier: LGPL-2.1-or-later /** * @file * * ELF files. * * See @ref ElfFile. */ #ifndef DRGN_ELF_FILE_H #define DRGN_ELF_FILE_H #include #include #include #include #include #include #include "binary_buffer.h" #include "elf_sections.h" // IWYU pragma: export #include "platform.h" struct drgn_module; /** * @ingroup Internals * * @defgroup ElfFile ELF files * * ELF file handling. * * @{ */ /** * Read the raw data from an ELF section, decompressing it first if it is * compressed. * * This returns an error if the section type is `SHT_NOBITS`. */ struct drgn_error *read_elf_section(Elf_Scn *scn, Elf_Data **ret); /** * Truncate any bytes beyond the last null character in an ELF string table. * * This sets `data->d_size` so that any string table index less than * `data->d_size` is guaranteed to be valid. */ void truncate_elf_string_data(Elf_Data *data); static inline bool elf_data_contains_ptr(Elf_Data *data, const void *ptr) { uintptr_t bufi = (uintptr_t)data->d_buf; uintptr_t ptri = (uintptr_t)ptr; return ptri >= bufi && ptri - bufi < data->d_size; } /** An ELF file used by a @ref drgn_module. */ struct drgn_elf_file { /** Module using this file. */ struct drgn_module *module; /** Filesystem path to this file. */ char *path; /** * Memory image backing @ref elf. * * @c NULL if not backed by a memory image. */ char *image; /** * File descriptor backing @ref elf. * * -1 if not backed by a file. */ int fd; /** Whether the file is loadable. */ bool is_loadable; /** Whether the file is relocatable. */ bool is_relocatable; /** Whether the file still need to have relocations applied. */ bool needs_relocation; /** Whether the file is a Linux kernel image (`vmlinux`). */ bool is_vmlinux; /** libelf handle. */ Elf *elf; /** * libdw handle. * * @c NULL if not yet created. * * Don't access this directly. Get it with @ref * drgn_elf_file_get_dwarf() instead. */ Dwarf *_dwarf; /** * Platform of this file. * * This should take precedence over @ref drgn_program::platform when * parsing this file. Note that there are some cases where it doesn't * make sense for the program and file platforms to differ (e.g., stack * unwinding), in which case the file should be ignored if its platform * doesn't match the program's. */ struct drgn_platform platform; /** Important ELF sections. */ Elf_Scn *scns[DRGN_SECTION_INDEX_NUM]; /** Data cached for important ELF sections. */ Elf_Data *scn_data[DRGN_SECTION_INDEX_NUM_DATA]; /** * If the file has a debugaltlink file, the debugaltlink file's * `.debug_info` section data. */ Elf_Data *alt_debug_info_data; /** * If the file has a debugaltlink file, the debugaltlink file's * `.debug_str` section data. */ Elf_Data *alt_debug_str_data; /** * For relocatable files, a bitmap of which sections have their address * set. */ unsigned long *sections_with_address; }; /** * Create a @ref drgn_elf_file. * * On success, this takes ownership of @p fd, @p image, and @p elf. @p path is * copied. */ struct drgn_error *drgn_elf_file_create(struct drgn_module *module, const char *path, int fd, char *image, Elf *elf, struct drgn_elf_file **ret); void drgn_elf_file_destroy(struct drgn_elf_file *file); /** Apply ELF relocations to the file if needed. */ struct drgn_error * drgn_elf_file_apply_relocations(struct drgn_elf_file *file); /** * Read an indexed ELF section. * * This applies ELF relocations to the file first if needed. */ struct drgn_error *drgn_elf_file_read_section(struct drgn_elf_file *file, enum drgn_section_index scn, Elf_Data **ret); struct drgn_error *drgn_elf_file_get_dwarf(struct drgn_elf_file *file, Dwarf **ret); static inline bool drgn_elf_file_is_little_endian(const struct drgn_elf_file *file) { return drgn_platform_is_little_endian(&file->platform); } static inline bool drgn_elf_file_bswap(const struct drgn_elf_file *file) { return drgn_platform_bswap(&file->platform); } static inline bool drgn_elf_file_is_64_bit(const struct drgn_elf_file *file) { return drgn_platform_is_64_bit(&file->platform); } static inline uint8_t drgn_elf_file_address_size(const struct drgn_elf_file *file) { return drgn_platform_address_size(&file->platform); } static inline uint64_t drgn_elf_file_address_mask(const struct drgn_elf_file *file) { return drgn_platform_address_mask(&file->platform); } static inline bool drgn_elf_file_has_dwarf(const struct drgn_elf_file *file) { return (file->scns[DRGN_SCN_DEBUG_INFO] && file->scns[DRGN_SCN_DEBUG_ABBREV]); } struct drgn_error * drgn_elf_file_section_error(struct drgn_elf_file *file, Elf_Scn *scn, Elf_Data *data, const char *ptr, const char *message) __attribute__((__returns_nonnull__)); struct drgn_error * drgn_elf_file_section_errorf(struct drgn_elf_file *file, Elf_Scn *scn, Elf_Data *data, const char *ptr, const char *format, ...) __attribute__((__returns_nonnull__, __format__(__printf__, 5, 6))); struct drgn_elf_file_section_buffer { struct binary_buffer bb; struct drgn_elf_file *file; Elf_Scn *scn; Elf_Data *data; }; struct drgn_error *drgn_elf_file_section_buffer_error(struct binary_buffer *bb, const char *ptr, const char *message); static inline void drgn_elf_file_section_buffer_init(struct drgn_elf_file_section_buffer *buffer, struct drgn_elf_file *file, Elf_Scn *scn, Elf_Data *data) { binary_buffer_init(&buffer->bb, data->d_buf, data->d_size, drgn_elf_file_is_little_endian(file), drgn_elf_file_section_buffer_error); buffer->file = file; buffer->scn = scn; buffer->data = data; } /** * Initialize a @ref binary_buffer for an indexed ELF section that has already * been read. */ static inline void drgn_elf_file_section_buffer_init_index(struct drgn_elf_file_section_buffer *buffer, struct drgn_elf_file *file, enum drgn_section_index scn) { drgn_elf_file_section_buffer_init(buffer, file, file->scns[scn], file->scn_data[scn]); } /** * Read an indexed ELF section (applying ELF relocations if needed) and * initialize a @ref binary_buffer for it. */ static inline struct drgn_error * drgn_elf_file_section_buffer_read(struct drgn_elf_file_section_buffer *buffer, struct drgn_elf_file *file, enum drgn_section_index scn) { Elf_Data *data; struct drgn_error *err = drgn_elf_file_read_section(file, scn, &data); if (err) return err; drgn_elf_file_section_buffer_init(buffer, file, file->scns[scn], data); return NULL; } /** * Return the virtual address range of an ELF file. * * @param[out] start_ret Minimum virtual address (inclusive). * @param[out] end_ret Maximum virtual address (exclusive). */ bool drgn_elf_file_address_range(struct drgn_elf_file *file, uint64_t *start_ret, uint64_t *end_ret); /** * Return whether an ELF file is a vmlinux file. * * @return > 0 if the file is vmlinux, 0 if it is not, < 0 on libelf error. */ int elf_is_vmlinux(Elf *elf); /** * Get the Linux release from a vmlinux file. * * @param[out] ret Returned release. * @return Length of @p ret on success, 0 if not found, < 0 on libelf error. */ ssize_t elf_vmlinux_release(Elf *elf, const char **ret); /** @} */ #endif /* DRGN_ELF_FILE_H */