| 1 |
// Copyright (c) Meta Platforms, Inc. and affiliates. |
| 2 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 3 |
|
| 4 |
/** |
| 5 |
* @file |
| 6 |
* |
| 7 |
* ELF note parsing. |
| 8 |
*/ |
| 9 |
|
| 10 |
#ifndef DRGN_ELF_NOTES_H |
| 11 |
#define DRGN_ELF_NOTES_H |
| 12 |
|
| 13 |
#include <elfutils/version.h> |
| 14 |
#include <gelf.h> |
| 15 |
#include <stdbool.h> |
| 16 |
|
| 17 |
/** |
| 18 |
* Parse the next ELF note out of a buffer. |
| 19 |
* |
| 20 |
* @note |
| 21 |
* Alignment of ELF notes is a mess. The [System V |
| 22 |
* gABI](http://www.sco.com/developers/gabi/latest/ch5.pheader.html#note_section) |
| 23 |
* says that the note header and descriptor should be aligned to 4 bytes for |
| 24 |
* 32-bit files and 8 bytes for 64-bit files. However, on Linux, 4-byte |
| 25 |
* alignment is used for both 32-bit and 64-bit files. |
| 26 |
* @note |
| 27 |
* The only exception as of 2024 is `NT_GNU_PROPERTY_TYPE_0`, which is defined |
| 28 |
* to follow the gABI alignment. See |
| 29 |
* ["PT_NOTE alignment, NT_GNU_PROPERTY_TYPE_0, glibc and gold"](https://public-inbox.org/libc-alpha/[email protected]/). |
| 30 |
* But, note that the 12-byte note header plus the 4-byte `"GNU\0"` name is a |
| 31 |
* multiple of 8 bytes, and the `NT_GNU_PROPERTY_TYPE_0` descriptor is defined |
| 32 |
* to be a multiple of 4 bytes for 32-bit files and 8 bytes for 64-bit files. As |
| 33 |
* a result, `NT_GNU_PROPERTY_TYPE_0` is never actually padded, and 4-byte vs. |
| 34 |
* 8-byte alignment are equivalent for parsing purposes. |
| 35 |
* @note |
| 36 |
* According to the [gABI Linux |
| 37 |
* Extensions](https://gitlab.com/x86-psABIs/Linux-ABI), consumers are now |
| 38 |
* supposed to use the `p_align` of the `PT_NOTE` segment instead of assuming an |
| 39 |
* alignment. However, the Linux kernel as of 6.0 generates core dumps with |
| 40 |
* `PT_NOTE` segments with a `p_align` of 0 or 1 which are actually aligned to 4 |
| 41 |
* bytes. So, when parsing notes from an ELF file, you need to use 8-byte |
| 42 |
* alignment if `p_align` is 8 and 4-byte alignment otherwise. binutils and |
| 43 |
* elfutils appear to do the same. |
| 44 |
* @note |
| 45 |
* Before Linux kernel commit f7ba52f302fd ("vmlinux.lds.h: Discard |
| 46 |
* .note.gnu.property section") (in v6.4), the vmlinux linker script can create |
| 47 |
* a `PT_NOTE` segment with a `p_align` of 8 where the entries other than |
| 48 |
* `NT_GNU_PROPERTY_TYPE_0` are actually aligned to 4 bytes. |
| 49 |
* @note |
| 50 |
* Finally, there are cases where we don't know `p_align`. For example, |
| 51 |
* `/sys/kernel/notes` contains the contents of the vmlinux `.notes` section, |
| 52 |
* which (ignoring the aforementioned bug) we can assume has 4-byte alignment. |
| 53 |
* As another example, `/sys/module/$module/notes/` contains a file for each |
| 54 |
* note section. Since `NT_GNU_PROPERTY_TYPE_0` can be parsed assuming 4-byte |
| 55 |
* alignment, we can again assume 4-byte alignment. This will work as long as |
| 56 |
* any future note types requiring 8-byte alignment also happen to have an |
| 57 |
* 8-byte aligned header+name and descriptor (but hopefully no one ever adds an |
| 58 |
* 8-byte aligned note again). |
| 59 |
* |
| 60 |
* @param[in,out] p Current position. Initialize to the beginning of the buffer. |
| 61 |
* @param[in,out] size Remaining size. Initialize to the size of the buffer. |
| 62 |
* @param[in] align Note alignment. Usually `p_align == 8 ? 8 : 4` if the |
| 63 |
* program header is available, otherwise 4. |
| 64 |
* @param[in] bswap Whether the note header needs to be byte-swapped. |
| 65 |
* @param[out] name_ret Returned note name. |
| 66 |
* @param[out] desc_ret Returned note descriptor. |
| 67 |
* @return @c true if a note was parsed, @c false if there are no more notes. |
| 68 |
*/ |
| 69 |
bool next_elf_note(const void **p, size_t *size, unsigned int align, bool bswap, |
| 70 |
GElf_Nhdr *nhdr_ret, const char **name_ret, |
| 71 |
const void **desc_ret); |
| 72 |
|
| 73 |
/** |
| 74 |
* Find an ELF note matching the given name and type. |
| 75 |
* |
| 76 |
* Note that this currently only checks segments, not sections. |
| 77 |
* |
| 78 |
* @return 0 on success, -1 on libelf error. |
| 79 |
*/ |
| 80 |
int find_elf_note(Elf *elf, const char *name, uint32_t type, const void **ret, |
| 81 |
size_t *size_ret); |
| 82 |
|
| 83 |
|
| 84 |
/** |
| 85 |
* Parse a GNU build ID from a buffer containing note data. |
| 86 |
* |
| 87 |
* @param[in] buf Buffer containing note data. |
| 88 |
* @param[in] size Size of @p buf in bytes. |
| 89 |
* @param[in] align Note alignment. See @ref next_elf_note(). |
| 90 |
* @param[in] bswap Whether the note header needs to be byte-swapped. |
| 91 |
* @param[out] ret Returned build ID, or @c NULL if not found. |
| 92 |
* @return Size of returned build ID in bytes, or @c NULL if not found. |
| 93 |
*/ |
| 94 |
size_t parse_gnu_build_id_from_notes(const void *buf, size_t size, |
| 95 |
unsigned int align, bool bswap, |
| 96 |
const void **ret); |
| 97 |
|
| 98 |
#if _ELFUTILS_PREREQ(0, 175) |
| 99 |
/** |
| 100 |
* Find an ELF file's GNU build ID, working around `vmlinux` files with broken |
| 101 |
* note alignment when possible. |
| 102 |
* |
| 103 |
* @param[out] ret Returned build ID, or @c NULL if not found. |
| 104 |
* @return Size of returned build ID in bytes, or @c NULL if not found. |
| 105 |
*/ |
| 106 |
ssize_t drgn_elf_gnu_build_id(Elf *elf, const void **ret); |
| 107 |
#else |
| 108 |
#include <elfutils/libdwelf.h> |
| 109 |
|
| 110 |
static inline ssize_t drgn_elf_gnu_build_id(Elf *elf, const void **ret) |
| 111 |
{ |
| 112 |
return dwelf_elf_gnu_build_id(elf, ret); |
| 113 |
} |
| 114 |
#endif |
| 115 |
|
| 116 |
static inline Elf_Type note_header_type(uint64_t p_align) |
| 117 |
{ |
| 118 |
#if _ELFUTILS_PREREQ(0, 175) |
| 119 |
if (p_align == 8) |
| 120 |
return ELF_T_NHDR8; |
| 121 |
#endif |
| 122 |
return ELF_T_NHDR; |
| 123 |
} |
| 124 |
|
| 125 |
#endif /* DRGN_ELF_NOTES_H */ |