OLD | NEW |
| (Empty) |
1 // Copyright 2014 The Crashpad Authors. All rights reserved. | |
2 // | |
3 // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 // you may not use this file except in compliance with the License. | |
5 // You may obtain a copy of the License at | |
6 // | |
7 // http://www.apache.org/licenses/LICENSE-2.0 | |
8 // | |
9 // Unless required by applicable law or agreed to in writing, software | |
10 // distributed under the License is distributed on an "AS IS" BASIS, | |
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 // See the License for the specific language governing permissions and | |
13 // limitations under the License. | |
14 | |
15 #ifndef CRASHPAD_UTIL_MAC_MACH_O_IMAGE_READER_H_ | |
16 #define CRASHPAD_UTIL_MAC_MACH_O_IMAGE_READER_H_ | |
17 | |
18 #include <mach/mach.h> | |
19 #include <stdint.h> | |
20 | |
21 #include <map> | |
22 #include <string> | |
23 | |
24 #include "base/basictypes.h" | |
25 #include "base/memory/scoped_ptr.h" | |
26 #include "util/misc/initialization_state_dcheck.h" | |
27 #include "util/misc/uuid.h" | |
28 #include "util/stdlib/pointer_container.h" | |
29 #include "util/mac/process_types.h" | |
30 | |
31 namespace crashpad { | |
32 | |
33 class MachOImageSegmentReader; | |
34 class MachOImageSymbolTableReader; | |
35 class ProcessReader; | |
36 | |
37 //! \brief A reader for Mach-O images mapped into another process. | |
38 //! | |
39 //! This class is capable of reading both 32-bit (`mach_header`/`MH_MAGIC`) and | |
40 //! 64-bit (`mach_header_64`/`MH_MAGIC_64`) images based on the bitness of the | |
41 //! remote process. | |
42 class MachOImageReader { | |
43 public: | |
44 MachOImageReader(); | |
45 ~MachOImageReader(); | |
46 | |
47 //! \brief Reads the Mach-O image file’s load commands from another process. | |
48 //! | |
49 //! This method must only be called once on an object. This method must be | |
50 //! called successfully before any other method in this class may be called. | |
51 //! | |
52 //! \param[in] process_reader The reader for the remote process. | |
53 //! \param[in] address The address, in the remote process’ address space, | |
54 //! where the `mach_header` or `mach_header_64` at the beginning of the | |
55 //! image to be read is located. This address can be determined by reading | |
56 //! the remote process’ dyld information (see | |
57 //! util/mac/process_types/dyld_images.proctype). | |
58 //! \param[in] name The module’s name, a string to be used in logged messages. | |
59 //! This string is for diagnostic purposes only, and may be empty. | |
60 //! | |
61 //! \return `true` if the image was read successfully, including all load | |
62 //! commands. `false` otherwise, with an appropriate message logged. | |
63 bool Initialize(ProcessReader* process_reader, | |
64 mach_vm_address_t address, | |
65 const std::string& name); | |
66 | |
67 //! \brief Returns the Mach-O file type. | |
68 //! | |
69 //! This value comes from the `filetype` field of the `mach_header` or | |
70 //! `mach_header_64`. Common values include `MH_EXECUTE`, `MH_DYLIB`, | |
71 //! `MH_DYLINKER`, and `MH_BUNDLE`. | |
72 uint32_t FileType() const { return file_type_; } | |
73 | |
74 //! \brief Returns the Mach-O image’s load address. | |
75 //! | |
76 //! This is the value passed as \a address to Initialize(). | |
77 mach_vm_address_t Address() const { return address_; } | |
78 | |
79 //! \brief Returns the mapped size of the Mach-O image’s `__TEXT` segment. | |
80 //! | |
81 //! Note that this is returns only the size of the `__TEXT` segment, not of | |
82 //! any other segment. This is because the interface only allows one load | |
83 //! address and size to be reported, but Mach-O image files may consist of | |
84 //! multiple discontiguous segments. By convention, the `__TEXT` segment is | |
85 //! always mapped at the beginning of a Mach-O image file, and it is the most | |
86 //! useful for the expected intended purpose of collecting data to obtain | |
87 //! stack backtraces. The implementation insists during initialization that | |
88 //! the `__TEXT` segment be mapped at the beginning of the file. | |
89 //! | |
90 //! In practice, discontiguous segments are only found for images that have | |
91 //! loaded out of the dyld shared cache, but the `__TEXT` segment’s size is | |
92 //! returned for modules that loaded with contiguous segments as well for | |
93 //! consistency. | |
94 mach_vm_size_t Size() const { return size_; } | |
95 | |
96 //! \brief Returns the Mach-O image’s “slide,” the difference between its | |
97 //! actual load address and its preferred load address. | |
98 //! | |
99 //! “Slide” is computed by subtracting the `__TEXT` segment’s preferred load | |
100 //! address from its actual load address. It will be reported as a positive | |
101 //! offset when the actual load address is greater than the preferred load | |
102 //! address. The preferred load address is taken to be the segment’s reported | |
103 //! `vmaddr` value. | |
104 mach_vm_size_t Slide() const { return slide_; } | |
105 | |
106 //! \brief Obtain segment information by segment name. | |
107 //! | |
108 //! \param[in] segment_name The name of the segment to search for, for | |
109 //! example, `"__TEXT"`. | |
110 //! | |
111 //! \return A pointer to the segment information if it was found, or `nullptr` | |
112 //! if it was not found. The caller does not take ownership; the lifetime | |
113 //! of the returned object is scoped to the lifetime of this | |
114 //! MachOImageReader object. | |
115 const MachOImageSegmentReader* GetSegmentByName( | |
116 const std::string& segment_name) const; | |
117 | |
118 //! \brief Obtain section information by segment and section name. | |
119 //! | |
120 //! \param[in] segment_name The name of the segment to search for, for | |
121 //! example, `"__TEXT"`. | |
122 //! \param[in] section_name The name of the section within the segment to | |
123 //! search for, for example, `"__text"`. | |
124 //! \param[out] address The actual address that the section was loaded at in | |
125 //! memory, taking any “slide” into account if the section did not load at | |
126 //! its preferred address as stored in the Mach-O image file. This | |
127 //! parameter can be `nullptr`. | |
128 //! | |
129 //! \return A pointer to the section information if it was found, or `nullptr` | |
130 //! if it was not found. The caller does not take ownership; the lifetime | |
131 //! of the returned object is scoped to the lifetime of this | |
132 //! MachOImageReader object. | |
133 //! | |
134 //! No parameter is provided for the section’s size, because it can be | |
135 //! obtained from the returned process_types::section::size field. | |
136 //! | |
137 //! \note The process_types::section::addr field gives the section’s preferred | |
138 //! load address as stored in the Mach-O image file, and is not adjusted | |
139 //! for any “slide” that may have occurred when the image was loaded. Use | |
140 //! \a address to obtain the section’s actual load address. | |
141 const process_types::section* GetSectionByName( | |
142 const std::string& segment_name, | |
143 const std::string& section_name, | |
144 mach_vm_address_t* address) const; | |
145 | |
146 //! \brief Obtain section information by section index. | |
147 //! | |
148 //! \param[in] index The index of the section to return, in the order that it | |
149 //! appears in the segment load commands. This is a 1-based index, | |
150 //! matching the section number values used for `nlist::n_sect`. | |
151 //! \param[out] containing_segment The segment that contains the section. | |
152 //! This parameter can be `nullptr`. The caller does not take ownership; | |
153 //! the lifetime of the returned object is scoped to the lifetime of this | |
154 //! MachOImageReader object. | |
155 //! \param[out] address The actual address that the section was loaded at in | |
156 //! memory, taking any “slide” into account if the section did not load at | |
157 //! its preferred address as stored in the Mach-O image file. This | |
158 //! parameter can be `nullptr`. | |
159 //! | |
160 //! \return A pointer to the section information. If \a index is out of range, | |
161 //! logs a warning and returns `nullptr`. The caller does not take | |
162 //! ownership; the lifetime of the returned object is scoped to the | |
163 //! lifetime of this MachOImageReader object. | |
164 //! | |
165 //! No parameter is provided for the section’s size, because it can be | |
166 //! obtained from the returned process_types::section::size field. | |
167 //! | |
168 //! \note The process_types::section::addr field gives the section’s preferred | |
169 //! load address as stored in the Mach-O image file, and is not adjusted | |
170 //! for any “slide” that may have occurred when the image was loaded. Use | |
171 //! \a address to obtain the section’s actual load address. | |
172 //! \note Unlike MachOImageSegmentReader::GetSectionAtIndex(), this method | |
173 //! accepts out-of-range values for \a index, and returns `nullptr` | |
174 //! instead of aborting execution upon encountering an out-of-range value. | |
175 //! This is because a Mach-O image file’s symbol table refers to this | |
176 //! per-module section index, and an out-of-range index in that case | |
177 //! should be treated as a data error (where the data is beyond this | |
178 //! code’s control) and handled non-fatally by reporting the error to the | |
179 //! caller. | |
180 const process_types::section* GetSectionAtIndex( | |
181 size_t index, | |
182 const MachOImageSegmentReader** containing_segment, | |
183 mach_vm_address_t* address) const; | |
184 | |
185 //! \brief Looks up a symbol in the image’s symbol table. | |
186 //! | |
187 //! This method is capable of locating external defined symbols. Specifically, | |
188 //! this method can look up symbols that have these charcteristics: | |
189 //! - `N_STAB` (debugging) and `N_PEXT` (private external) must not be set. | |
190 //! - `N_EXT` (external) must be set. | |
191 //! - The type must be `N_ABS` (absolute) or `N_SECT` (defined in section). | |
192 //! | |
193 //! `N_INDR` (indirect), `N_UNDF` (undefined), and `N_PBUD` (prebound | |
194 //! undefined) symbols cannot be located through this mechanism. | |
195 //! | |
196 //! \param[in] name The name of the symbol to look up, “mangled” or | |
197 //! “decorated” appropriately. For example, use `"_main"` to look up the | |
198 //! symbol for the C `main()` function, and use `"__Z4Funcv"` to look up | |
199 //! the symbol for the C++ `Func()` function. Contrary to `dlsym()`, the | |
200 //! leading underscore must not be stripped when using this interface. | |
201 //! \param[out] value If the lookup was successful, this will be set to the | |
202 //! value of the symbol, adjusted for any “slide” as needed. The value can | |
203 //! be used as an address in the remote process’ address space where the | |
204 //! pointee of the symbol exists in memory. | |
205 //! | |
206 //! \return `true` if the symbol lookup was successful and the symbol was | |
207 //! found. `false` otherwise, including error conditions (for which a | |
208 //! warning message will be logged), modules without symbol tables, and | |
209 //! symbol names not found in the symbol table. | |
210 //! | |
211 //! \note Symbol values returned via this interface are adjusted for “slide” | |
212 //! as appropriate, in contrast to the underlying implementation, | |
213 //! MachOImageSymbolTableReader::LookUpExternalDefinedSymbol(). | |
214 //! | |
215 //! \warning Symbols that are resolved by running symbol resolvers | |
216 //! (`.symbol_resolver`) are not properly handled by this interface. The | |
217 //! address of the symbol resolver is returned because that’s what shows | |
218 //! up in the symbol table, rather than the effective address of the | |
219 //! resolved symbol as used by dyld after running the resolver. The only | |
220 //! way to detect this situation would be to read the `LC_DYLD_INFO` or | |
221 //! `LC_DYLD_INFO_ONLY` load command if present and looking for the | |
222 //! `EXPORT_SYMBOL_FLAGS_STUB_AND_RESOLVER` flag, but that would just be | |
223 //! able to detect symbols with a resolver, it would not be able to | |
224 //! resolve them from out-of-process, so it’s not currently done. | |
225 bool LookUpExternalDefinedSymbol(const std::string& name, | |
226 mach_vm_address_t* value) const; | |
227 | |
228 //! \brief Returns a Mach-O dylib image’s current version. | |
229 //! | |
230 //! This information comes from the `dylib_current_version` field of a dylib’s | |
231 //! `LC_ID_DYLIB` load command. For dylibs without this load command, `0` will | |
232 //! be returned. | |
233 //! | |
234 //! This method may only be called on Mach-O images for which FileType() | |
235 //! returns `MH_DYLIB`. | |
236 uint32_t DylibVersion() const; | |
237 | |
238 //! \brief Returns a Mach-O image’s source version. | |
239 //! | |
240 //! This information comes from a Mach-O image’s `LC_SOURCE_VERSION` load | |
241 //! command. For Mach-O images without this load command, `0` will be | |
242 //! returned. | |
243 uint64_t SourceVersion() const { return source_version_; } | |
244 | |
245 //! \brief Returns a Mach-O image’s UUID. | |
246 //! | |
247 //! This information comes from a Mach-O image’s `LC_UUID` load command. For | |
248 //! Mach-O images without this load command, a zeroed-out UUID value will be | |
249 //! returned. | |
250 // | |
251 // UUID is a name in this scope (referring to this method), so the parameter’s | |
252 // type needs to be qualified with |crashpad::|. | |
253 void UUID(crashpad::UUID* uuid) const; | |
254 | |
255 //! \brief Returns the dynamic linker’s pathname. | |
256 //! | |
257 //! The dynamic linker is normally /usr/lib/dyld. | |
258 //! | |
259 //! For executable images (those with file type `MH_EXECUTE`), this is the | |
260 //! name provided in the `LC_LOAD_DYLINKER` load command, if any. For dynamic | |
261 //! linker images (those with file type `MH_DYLINKER`), this is the name | |
262 //! provided in the `LC_ID_DYLINKER` load command. In other cases, this will | |
263 //! be empty. | |
264 std::string DylinkerName() const { return dylinker_name_; } | |
265 | |
266 private: | |
267 // A generic helper routine for the other Read*Command() methods. | |
268 template <typename T> | |
269 bool ReadLoadCommand(mach_vm_address_t load_command_address, | |
270 const std::string& load_command_info, | |
271 uint32_t expected_load_command_id, | |
272 T* load_command); | |
273 | |
274 // The Read*Command() methods are subroutines called by Initialize(). They are | |
275 // responsible for reading a single load command. They may update the member | |
276 // fields of their MachOImageReader object. If they can’t make sense of a load | |
277 // command, they return false. | |
278 bool ReadSegmentCommand(mach_vm_address_t load_command_address, | |
279 const std::string& load_command_info); | |
280 bool ReadSymTabCommand(mach_vm_address_t load_command_address, | |
281 const std::string& load_command_info); | |
282 bool ReadDySymTabCommand(mach_vm_address_t load_command_address, | |
283 const std::string& load_command_info); | |
284 bool ReadIdDylibCommand(mach_vm_address_t load_command_address, | |
285 const std::string& load_command_info); | |
286 bool ReadDylinkerCommand(mach_vm_address_t load_command_address, | |
287 const std::string& load_command_info); | |
288 bool ReadUUIDCommand(mach_vm_address_t load_command_address, | |
289 const std::string& load_command_info); | |
290 bool ReadSourceVersionCommand(mach_vm_address_t load_command_address, | |
291 const std::string& load_command_info); | |
292 bool ReadUnexpectedCommand(mach_vm_address_t load_command_address, | |
293 const std::string& load_command_info); | |
294 | |
295 // Performs deferred initialization of the symbol table. Because a module’s | |
296 // symbol table is often not needed, this is not handled in Initialize(), but | |
297 // is done lazily, on-demand as needed. | |
298 // | |
299 // symbol_table_initialized_ will be transitioned to the appropriate state. If | |
300 // initialization completes successfully, this will be the valid state. | |
301 // Otherwise, it will be left in the invalid state and a warning message will | |
302 // be logged. | |
303 // | |
304 // Note that if the object contains no symbol table, symbol_table_initialized_ | |
305 // will be set to the valid state, but symbol_table_ will be nullptr. | |
306 void InitializeSymbolTable() const; | |
307 | |
308 PointerVector<MachOImageSegmentReader> segments_; | |
309 std::map<std::string, size_t> segment_map_; | |
310 std::string module_info_; | |
311 std::string dylinker_name_; | |
312 crashpad::UUID uuid_; | |
313 mach_vm_address_t address_; | |
314 mach_vm_size_t size_; | |
315 mach_vm_size_t slide_; | |
316 uint64_t source_version_; | |
317 scoped_ptr<process_types::symtab_command> symtab_command_; | |
318 scoped_ptr<process_types::dysymtab_command> dysymtab_command_; | |
319 | |
320 // symbol_table_ (and symbol_table_initialized_) are mutable in order to | |
321 // maintain LookUpExternalDefinedSymbol() as a const interface while allowing | |
322 // lazy initialization via InitializeSymbolTable(). This is logical | |
323 // const-ness, not physical const-ness. | |
324 mutable scoped_ptr<MachOImageSymbolTableReader> symbol_table_; | |
325 | |
326 scoped_ptr<process_types::dylib_command> id_dylib_command_; | |
327 ProcessReader* process_reader_; // weak | |
328 uint32_t file_type_; | |
329 InitializationStateDcheck initialized_; | |
330 | |
331 // symbol_table_initialized_ protects symbol_table_: symbol_table_ can only | |
332 // be used when symbol_table_initialized_ is valid, although | |
333 // symbol_table_initialized_ being valid doesn’t imply that symbol_table_ is | |
334 // set. symbol_table_initialized_ will be valid without symbol_table_ being | |
335 // set in modules that have no symbol table. | |
336 mutable InitializationState symbol_table_initialized_; | |
337 | |
338 DISALLOW_COPY_AND_ASSIGN(MachOImageReader); | |
339 }; | |
340 | |
341 } // namespace crashpad | |
342 | |
343 #endif // CRASHPAD_UTIL_MAC_MACH_O_IMAGE_READER_H_ | |
OLD | NEW |