1 //===-- ProcessElfCore.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 // Notes about Linux Process core dumps:
8 //  1) Linux core dump is stored as ELF file.
9 //  2) The ELF file's PT_NOTE and PT_LOAD segments describes the program's
10 //     address space and thread contexts.
11 //  3) PT_NOTE segment contains note entries which describes a thread context.
12 //  4) PT_LOAD segment describes a valid contiguous range of process address
13 //     space.
14 //===----------------------------------------------------------------------===//
15 
16 #ifndef LLDB_SOURCE_PLUGINS_PROCESS_ELF_CORE_PROCESSELFCORE_H
17 #define LLDB_SOURCE_PLUGINS_PROCESS_ELF_CORE_PROCESSELFCORE_H
18 
19 #include <list>
20 #include <vector>
21 
22 #include "lldb/Target/PostMortemProcess.h"
23 #include "lldb/Utility/ConstString.h"
24 #include "lldb/Utility/Status.h"
25 
26 #include "Plugins/ObjectFile/ELF/ELFHeader.h"
27 #include "Plugins/Process/elf-core/RegisterUtilities.h"
28 
29 struct ThreadData;
30 
31 class ProcessElfCore : public lldb_private::PostMortemProcess {
32 public:
33   // Constructors and Destructors
34   static lldb::ProcessSP
35   CreateInstance(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp,
36                  const lldb_private::FileSpec *crash_file_path,
37                  bool can_connect);
38 
39   static void Initialize();
40 
41   static void Terminate();
42 
43   static llvm::StringRef GetPluginNameStatic() { return "elf-core"; }
44 
45   static llvm::StringRef GetPluginDescriptionStatic();
46 
47   // Constructors and Destructors
48   ProcessElfCore(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp,
49                  const lldb_private::FileSpec &core_file);
50 
51   ~ProcessElfCore() override;
52 
53   // Check if a given Process
54   bool CanDebug(lldb::TargetSP target_sp,
55                 bool plugin_specified_by_name) override;
56 
57   // Creating a new process, or attaching to an existing one
58   lldb_private::Status DoLoadCore() override;
59 
60   lldb_private::DynamicLoader *GetDynamicLoader() override;
61 
62   // PluginInterface protocol
63   llvm::StringRef GetPluginName() override { return GetPluginNameStatic(); }
64 
65   // Process Control
66   lldb_private::Status DoDestroy() override;
67 
68   void RefreshStateAfterStop() override;
69 
70   lldb_private::Status WillResume() override {
71     lldb_private::Status error;
72     error.SetErrorStringWithFormatv(
73         "error: {0} does not support resuming processes", GetPluginName());
74     return error;
75   }
76 
77   // Process Queries
78   bool IsAlive() override;
79 
80   bool WarnBeforeDetach() const override { return false; }
81 
82   // Process Memory
83   size_t ReadMemory(lldb::addr_t addr, void *buf, size_t size,
84                     lldb_private::Status &error) override;
85 
86   size_t DoReadMemory(lldb::addr_t addr, void *buf, size_t size,
87                       lldb_private::Status &error) override;
88 
89   // We do not implement DoReadMemoryTags. Instead all the work is done in
90   // ReadMemoryTags which avoids having to unpack and repack tags.
91   llvm::Expected<std::vector<lldb::addr_t>> ReadMemoryTags(lldb::addr_t addr,
92                                                            size_t len) override;
93 
94   lldb::addr_t GetImageInfoAddress() override;
95 
96   lldb_private::ArchSpec GetArchitecture();
97 
98   // Returns AUXV structure found in the core file
99   lldb_private::DataExtractor GetAuxvData() override;
100 
101   bool GetProcessInfo(lldb_private::ProcessInstanceInfo &info) override;
102 
103 protected:
104   void Clear();
105 
106   bool DoUpdateThreadList(lldb_private::ThreadList &old_thread_list,
107                           lldb_private::ThreadList &new_thread_list) override;
108 
109   lldb_private::Status
110   DoGetMemoryRegionInfo(lldb::addr_t load_addr,
111                         lldb_private::MemoryRegionInfo &region_info) override;
112 
113   bool SupportsMemoryTagging() override { return !m_core_tag_ranges.IsEmpty(); }
114 
115 private:
116   struct NT_FILE_Entry {
117     lldb::addr_t start;
118     lldb::addr_t end;
119     lldb::addr_t file_ofs;
120     lldb_private::ConstString path;
121   };
122 
123   // For ProcessElfCore only
124   typedef lldb_private::Range<lldb::addr_t, lldb::addr_t> FileRange;
125   typedef lldb_private::RangeDataVector<lldb::addr_t, lldb::addr_t, FileRange>
126       VMRangeToFileOffset;
127   typedef lldb_private::RangeDataVector<lldb::addr_t, lldb::addr_t, uint32_t>
128       VMRangeToPermissions;
129 
130   lldb::ModuleSP m_core_module_sp;
131   lldb_private::FileSpec m_core_file;
132   std::string m_dyld_plugin_name;
133 
134   // True if m_thread_contexts contains valid entries
135   bool m_thread_data_valid = false;
136 
137   // Contain thread data read from NOTE segments
138   std::vector<ThreadData> m_thread_data;
139 
140   // AUXV structure found from the NOTE segment
141   lldb_private::DataExtractor m_auxv;
142 
143   // Address ranges found in the core
144   VMRangeToFileOffset m_core_aranges;
145 
146   // Permissions for all ranges
147   VMRangeToPermissions m_core_range_infos;
148 
149   // Memory tag ranges found in the core
150   VMRangeToFileOffset m_core_tag_ranges;
151 
152   // NT_FILE entries found from the NOTE segment
153   std::vector<NT_FILE_Entry> m_nt_file_entries;
154 
155   // Parse thread(s) data structures(prstatus, prpsinfo) from given NOTE segment
156   llvm::Error ParseThreadContextsFromNoteSegment(
157       const elf::ELFProgramHeader &segment_header,
158       const lldb_private::DataExtractor &segment_data);
159 
160   // Returns number of thread contexts stored in the core file
161   uint32_t GetNumThreadContexts();
162 
163   // Parse a contiguous address range of the process from LOAD segment
164   lldb::addr_t
165   AddAddressRangeFromLoadSegment(const elf::ELFProgramHeader &header);
166 
167   // Parse a contiguous address range from a memory tag segment
168   lldb::addr_t
169   AddAddressRangeFromMemoryTagSegment(const elf::ELFProgramHeader &header);
170 
171   llvm::Expected<std::vector<lldb_private::CoreNote>>
172   parseSegment(const lldb_private::DataExtractor &segment);
173   llvm::Error parseFreeBSDNotes(llvm::ArrayRef<lldb_private::CoreNote> notes);
174   llvm::Error parseNetBSDNotes(llvm::ArrayRef<lldb_private::CoreNote> notes);
175   llvm::Error parseOpenBSDNotes(llvm::ArrayRef<lldb_private::CoreNote> notes);
176   llvm::Error parseLinuxNotes(llvm::ArrayRef<lldb_private::CoreNote> notes);
177 };
178 
179 #endif // LLDB_SOURCE_PLUGINS_PROCESS_ELF_CORE_PROCESSELFCORE_H
180