1 //===-- RegisterContext.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_REGISTERCONTEXT_H
10 #define LLDB_TARGET_REGISTERCONTEXT_H
11 
12 #include "lldb/Target/ExecutionContextScope.h"
13 #include "lldb/lldb-private.h"
14 
15 namespace lldb_private {
16 
17 class RegisterContext : public std::enable_shared_from_this<RegisterContext>,
18                         public ExecutionContextScope {
19 public:
20   // Constructors and Destructors
21   RegisterContext(Thread &thread, uint32_t concrete_frame_idx);
22 
23   ~RegisterContext() override;
24 
25   void InvalidateIfNeeded(bool force);
26 
27   // Subclasses must override these functions
28   virtual void InvalidateAllRegisters() = 0;
29 
30   virtual size_t GetRegisterCount() = 0;
31 
32   virtual const RegisterInfo *GetRegisterInfoAtIndex(size_t reg) = 0;
33 
34   virtual size_t GetRegisterSetCount() = 0;
35 
36   virtual const RegisterSet *GetRegisterSet(size_t reg_set) = 0;
37 
38   virtual lldb::ByteOrder GetByteOrder();
39 
40   virtual bool ReadRegister(const RegisterInfo *reg_info,
41                             RegisterValue &reg_value) = 0;
42 
43   virtual bool WriteRegister(const RegisterInfo *reg_info,
44                              const RegisterValue &reg_value) = 0;
45 
46   virtual bool ReadAllRegisterValues(lldb::WritableDataBufferSP &data_sp) {
47     return false;
48   }
49 
50   virtual bool WriteAllRegisterValues(const lldb::DataBufferSP &data_sp) {
51     return false;
52   }
53 
54   virtual bool RegisterWriteCausesReconfigure(const llvm::StringRef name) {
55     return false;
56   }
57 
58   virtual bool ReconfigureRegisterInfo() { return false; }
59 
60   // These two functions are used to implement "push" and "pop" of register
61   // states.  They are used primarily for expression evaluation, where we need
62   // to push a new state (storing the old one in data_sp) and then restoring
63   // the original state by passing the data_sp we got from ReadAllRegisters to
64   // WriteAllRegisterValues. ReadAllRegisters will do what is necessary to
65   // return a coherent set of register values for this thread, which may mean
66   // e.g. interrupting a thread that is sitting in a kernel trap.  That is a
67   // somewhat disruptive operation, so these API's should only be used when
68   // this behavior is needed.
69 
70   virtual bool
71   ReadAllRegisterValues(lldb_private::RegisterCheckpoint &reg_checkpoint);
72 
73   virtual bool WriteAllRegisterValues(
74       const lldb_private::RegisterCheckpoint &reg_checkpoint);
75 
76   bool CopyFromRegisterContext(lldb::RegisterContextSP context);
77 
78   /// Convert from a given register numbering scheme to the lldb register
79   /// numbering scheme
80   ///
81   /// There may be multiple ways to enumerate the registers for a given
82   /// architecture.  ABI references will specify one to be used with
83   /// DWARF, the register numberings from process plugin, there may
84   /// be a variation used for eh_frame unwind instructions (e.g. on Darwin),
85   /// and so on.  Register 5 by itself is meaningless - RegisterKind
86   /// enumeration tells you what context that number should be translated as.
87   ///
88   /// Inside lldb, register numbers are in the eRegisterKindLLDB scheme;
89   /// arguments which take a register number should take one in that
90   /// scheme.
91   ///
92   /// eRegisterKindGeneric is a special numbering scheme which gives us
93   /// constant values for the pc, frame register, stack register, etc., for
94   /// use within lldb.  They may not be defined for all architectures but
95   /// it allows generic code to translate these common registers into the
96   /// lldb numbering scheme.
97   ///
98   /// This method translates a given register kind + register number into
99   /// the eRegisterKindLLDB register numbering.
100   ///
101   /// \param [in] kind
102   ///     The register numbering scheme (RegisterKind) that the following
103   ///     register number is in.
104   ///
105   /// \param [in] num
106   ///     A register number in the 'kind' register numbering scheme.
107   ///
108   /// \return
109   ///     The equivalent register number in the eRegisterKindLLDB
110   ///     numbering scheme, if possible, else LLDB_INVALID_REGNUM.
111   virtual uint32_t ConvertRegisterKindToRegisterNumber(lldb::RegisterKind kind,
112                                                        uint32_t num);
113 
114   // Subclasses can override these functions if desired
115   virtual uint32_t NumSupportedHardwareBreakpoints();
116 
117   virtual uint32_t SetHardwareBreakpoint(lldb::addr_t addr, size_t size);
118 
119   virtual bool ClearHardwareBreakpoint(uint32_t hw_idx);
120 
121   virtual uint32_t NumSupportedHardwareWatchpoints();
122 
123   virtual uint32_t SetHardwareWatchpoint(lldb::addr_t addr, size_t size,
124                                          bool read, bool write);
125 
126   virtual bool ClearHardwareWatchpoint(uint32_t hw_index);
127 
128   virtual bool HardwareSingleStep(bool enable);
129 
130   virtual Status
131   ReadRegisterValueFromMemory(const lldb_private::RegisterInfo *reg_info,
132                               lldb::addr_t src_addr, uint32_t src_len,
133                               RegisterValue &reg_value);
134 
135   virtual Status
136   WriteRegisterValueToMemory(const lldb_private::RegisterInfo *reg_info,
137                              lldb::addr_t dst_addr, uint32_t dst_len,
138                              const RegisterValue &reg_value);
139 
140   // Subclasses should not override these
141   virtual lldb::tid_t GetThreadID() const;
142 
143   virtual Thread &GetThread() { return m_thread; }
144 
145   const RegisterInfo *GetRegisterInfoByName(llvm::StringRef reg_name,
146                                             uint32_t start_idx = 0);
147 
148   const RegisterInfo *GetRegisterInfo(lldb::RegisterKind reg_kind,
149                                       uint32_t reg_num);
150 
151   uint64_t GetPC(uint64_t fail_value = LLDB_INVALID_ADDRESS);
152 
153   // Returns the register value containing thread specific data, like TLS data
154   // and other thread specific stuff.
155   uint64_t GetThreadPointer(uint64_t fail_value = LLDB_INVALID_ADDRESS);
156 
157   /// Get an address suitable for symbolication.
158   /// When symbolicating -- computing line, block, function --
159   /// for a function in the middle of the stack, using the return
160   /// address can lead to unexpected results for the user.
161   /// A function that ends in a tail-call may have another function
162   /// as the "return" address, but it will never actually return.
163   /// Or a noreturn call in the middle of a function is the end of
164   /// a block of instructions, and a DWARF location list entry for
165   /// the return address may be a very different code path with
166   /// incorrect results when printing variables for this frame.
167   ///
168   /// At a source line view, the user expects the current-line indictation
169   /// to point to the function call they're under, not the next source line.
170   ///
171   /// The return address (GetPC()) should always be shown to the user,
172   /// but when computing context, keeping within the bounds of the
173   /// call instruction is what the user expects to see.
174   ///
175   /// \param [out] address
176   ///     An Address object that will be filled in, if a PC can be retrieved.
177   ///
178   /// \return
179   ///     Returns true if the Address param was filled in.
180   bool GetPCForSymbolication(Address &address);
181 
182   bool SetPC(uint64_t pc);
183 
184   bool SetPC(Address addr);
185 
186   uint64_t GetSP(uint64_t fail_value = LLDB_INVALID_ADDRESS);
187 
188   bool SetSP(uint64_t sp);
189 
190   uint64_t GetFP(uint64_t fail_value = LLDB_INVALID_ADDRESS);
191 
192   bool SetFP(uint64_t fp);
193 
194   const char *GetRegisterName(uint32_t reg);
195 
196   uint64_t GetReturnAddress(uint64_t fail_value = LLDB_INVALID_ADDRESS);
197 
198   uint64_t GetFlags(uint64_t fail_value = 0);
199 
200   uint64_t ReadRegisterAsUnsigned(uint32_t reg, uint64_t fail_value);
201 
202   uint64_t ReadRegisterAsUnsigned(const RegisterInfo *reg_info,
203                                   uint64_t fail_value);
204 
205   bool WriteRegisterFromUnsigned(uint32_t reg, uint64_t uval);
206 
207   bool WriteRegisterFromUnsigned(const RegisterInfo *reg_info, uint64_t uval);
208 
209   bool ConvertBetweenRegisterKinds(lldb::RegisterKind source_rk,
210                                    uint32_t source_regnum,
211                                    lldb::RegisterKind target_rk,
212                                    uint32_t &target_regnum);
213 
214   // lldb::ExecutionContextScope pure virtual functions
215   lldb::TargetSP CalculateTarget() override;
216 
217   lldb::ProcessSP CalculateProcess() override;
218 
219   lldb::ThreadSP CalculateThread() override;
220 
221   lldb::StackFrameSP CalculateStackFrame() override;
222 
223   void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
224 
225   uint32_t GetStopID() const { return m_stop_id; }
226 
227   void SetStopID(uint32_t stop_id) { m_stop_id = stop_id; }
228 
229 protected:
230   /// Indicates that this frame is currently executing code,
231   /// that the PC value is not a return-pc but an actual executing
232   /// instruction.  Some places in lldb will treat a return-pc
233   /// value differently than the currently-executing-pc value,
234   /// and this method can indicate if that should be done.
235   /// The base class implementation only uses the frame index,
236   /// but subclasses may have additional information that they
237   /// can use to detect frames in this state, for instance a
238   /// frame above a trap handler (sigtramp etc)..
239   virtual bool BehavesLikeZerothFrame() const {
240     return m_concrete_frame_idx == 0;
241   }
242 
243   // Classes that inherit from RegisterContext can see and modify these
244   Thread &m_thread; // The thread that this register context belongs to.
245   uint32_t m_concrete_frame_idx; // The concrete frame index for this register
246                                  // context
247   uint32_t m_stop_id; // The stop ID that any data in this context is valid for
248 private:
249   // For RegisterContext only
250   RegisterContext(const RegisterContext &) = delete;
251   const RegisterContext &operator=(const RegisterContext &) = delete;
252 };
253 
254 } // namespace lldb_private
255 
256 #endif // LLDB_TARGET_REGISTERCONTEXT_H
257