1 | //===-- MemoryTagManager.h --------------------------------------*- C++ -*-===// |
2 | // |
3 | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
4 | // See https://llvm.org/LICENSE.txt for license information. |
5 | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
6 | // |
7 | //===----------------------------------------------------------------------===// |
8 | |
9 | #ifndef LLDB_TARGET_MEMORYTAGMANAGER_H |
10 | #define LLDB_TARGET_MEMORYTAGMANAGER_H |
11 | |
12 | #include "lldb/Target/MemoryRegionInfo.h" |
13 | #include "lldb/Utility/RangeMap.h" |
14 | #include "lldb/lldb-private.h" |
15 | #include "llvm/Support/Error.h" |
16 | |
17 | namespace lldb_private { |
18 | |
19 | // This interface allows high level commands to handle memory tags |
20 | // in a generic way. |
21 | // |
22 | // Definitions: |
23 | // logical tag - the tag stored in a pointer |
24 | // allocation tag - the tag stored in hardware |
25 | // (e.g. special memory, cache line bits) |
26 | // granule - number of bytes of memory a single tag applies to |
27 | |
28 | class MemoryTagManager { |
29 | public: |
30 | typedef Range<lldb::addr_t, lldb::addr_t> TagRange; |
31 | |
32 | // Extract the logical tag from a pointer |
33 | // The tag is returned as a plain value, with any shifts removed. |
34 | // For example if your tags are stored in bits 56-60 then the logical tag |
35 | // you get will have been shifted down 56 before being returned. |
36 | virtual lldb::addr_t GetLogicalTag(lldb::addr_t addr) const = 0; |
37 | |
38 | // Remove tag bits from a pointer |
39 | virtual lldb::addr_t RemoveTagBits(lldb::addr_t addr) const = 0; |
40 | |
41 | // Return the difference between two addresses, ignoring any logical tags they |
42 | // have. If your tags are just part of a larger set of ignored bits, this |
43 | // should ignore all those bits. |
44 | virtual ptrdiff_t AddressDiff(lldb::addr_t addr1, |
45 | lldb::addr_t addr2) const = 0; |
46 | |
47 | // Return the number of bytes a single tag covers |
48 | virtual lldb::addr_t GetGranuleSize() const = 0; |
49 | |
50 | // Align an address range to granule boundaries. |
51 | // So that reading memory tags for the new range returns |
52 | // tags that will cover the original range. |
53 | // |
54 | // Say your granules are 16 bytes and you want |
55 | // tags for 16 bytes of memory starting from address 8. |
56 | // 1 granule isn't enough because it only covers addresses |
57 | // 0-16, we want addresses 8-24. So the range must be |
58 | // expanded to 2 granules. |
59 | virtual TagRange ExpandToGranule(TagRange range) const = 0; |
60 | |
61 | // Given a range addr to end_addr, check that: |
62 | // * end_addr >= addr (when memory tags are removed) |
63 | // * the granule aligned range is completely covered by tagged memory |
64 | // (which may include one or more memory regions) |
65 | // |
66 | // If so, return a modified range which will have been expanded |
67 | // to be granule aligned. Otherwise return an error. |
68 | // |
69 | // Tags in the input addresses are ignored and not present |
70 | // in the returned range. |
71 | virtual llvm::Expected<TagRange> MakeTaggedRange( |
72 | lldb::addr_t addr, lldb::addr_t end_addr, |
73 | const lldb_private::MemoryRegionInfos &memory_regions) const = 0; |
74 | |
75 | // Given a range addr to end_addr, check that end_addr >= addr. |
76 | // If it is not, return an error saying so. |
77 | // Otherwise, granule align it and return a set of ranges representing |
78 | // subsections of the aligned range that have memory tagging enabled. |
79 | // |
80 | // Basically a sparse version of MakeTaggedRange. Use this when you |
81 | // want to know which parts of a larger range have memory tagging. |
82 | // |
83 | // Regions in memory_regions should be sorted in ascending order and |
84 | // not overlap. (use Process GetMemoryRegions) |
85 | // |
86 | // Tags in the input addresses are ignored and not present |
87 | // in the returned ranges. |
88 | virtual llvm::Expected<std::vector<TagRange>> MakeTaggedRanges( |
89 | lldb::addr_t addr, lldb::addr_t end_addr, |
90 | const lldb_private::MemoryRegionInfos &memory_regions) const = 0; |
91 | |
92 | // Return the type value to use in GDB protocol qMemTags packets to read |
93 | // allocation tags. This is named "Allocation" specifically because the spec |
94 | // allows for logical tags to be read the same way, though we do not use that. |
95 | // |
96 | // This value is unique within a given architecture. Meaning that different |
97 | // tagging schemes within the same architecture should use unique values, |
98 | // but other architectures can overlap those values. |
99 | virtual int32_t GetAllocationTagType() const = 0; |
100 | |
101 | // Return the number of bytes a single tag will be packed into during |
102 | // transport. For example an MTE tag is 4 bits but occupies 1 byte during |
103 | // transport. |
104 | virtual size_t GetTagSizeInBytes() const = 0; |
105 | |
106 | // Unpack tags from their stored format (e.g. gdb qMemTags data) into seperate |
107 | // tags. |
108 | // |
109 | // Checks that each tag is within the expected value range and if granules is |
110 | // set to non-zero, that the number of tags found matches the number of |
111 | // granules we expected to cover. |
112 | virtual llvm::Expected<std::vector<lldb::addr_t>> |
113 | UnpackTagsData(const std::vector<uint8_t> &tags, |
114 | size_t granules = 0) const = 0; |
115 | |
116 | // Unpack tags from a corefile segment containing compressed tags |
117 | // (compression that may be different from the one used for GDB transport). |
118 | // |
119 | // This method asumes that: |
120 | // * addr and len have been granule aligned by a tag manager |
121 | // * addr >= tag_segment_virtual_address |
122 | // |
123 | // 'reader' will always be a wrapper around a CoreFile in real use |
124 | // but allows testing without having to mock a CoreFile. |
125 | typedef std::function<size_t(lldb::offset_t, size_t, void *)> CoreReaderFn; |
126 | std::vector<lldb::addr_t> virtual UnpackTagsFromCoreFileSegment( |
127 | CoreReaderFn reader, lldb::addr_t tag_segment_virtual_address, |
128 | lldb::addr_t tag_segment_data_address, lldb::addr_t addr, |
129 | size_t len) const = 0; |
130 | |
131 | // Pack uncompressed tags into their storage format (e.g. for gdb QMemTags). |
132 | // Checks that each tag is within the expected value range. |
133 | // We do not check the number of tags or range they apply to because |
134 | // it is up to the remote to repeat them as needed. |
135 | virtual llvm::Expected<std::vector<uint8_t>> |
136 | PackTags(const std::vector<lldb::addr_t> &tags) const = 0; |
137 | |
138 | // Take a set of tags and repeat them as much as needed to cover the given |
139 | // range. We assume that this range has been previously expanded/aligned to |
140 | // granules. (this method is used by lldb-server to implement QMemTags |
141 | // packet handling) |
142 | // |
143 | // If the range is empty, zero tags are returned. |
144 | // If the range is not empty and... |
145 | // * there are no tags, an error is returned. |
146 | // * there are fewer tags than granules, the tags are repeated to fill the |
147 | // range. |
148 | // * there are more tags than granules, only the tags required to cover |
149 | // the range are returned. |
150 | // |
151 | // When repeating tags it will not always return a multiple of the original |
152 | // list. For example if your range is 3 granules and your tags are 1 and 2. |
153 | // You will get tags 1, 2 and 1 returned. Rather than getting 1, 2, 1, 2, |
154 | // which would be one too many tags for the range. |
155 | // |
156 | // A single tag will just be repeated as you'd expected. Tag 1 over 3 granules |
157 | // would return 1, 1, 1. |
158 | virtual llvm::Expected<std::vector<lldb::addr_t>> |
159 | RepeatTagsForRange(const std::vector<lldb::addr_t> &tags, |
160 | TagRange range) const = 0; |
161 | |
162 | virtual ~MemoryTagManager() = default; |
163 | }; |
164 | |
165 | } // namespace lldb_private |
166 | |
167 | #endif // LLDB_TARGET_MEMORYTAGMANAGER_H |
168 | |