Debian Codegraph @

libdrgn/elf_notes.h

raw
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 */