LLDB mainline
CommandObjectRegister.cpp
Go to the documentation of this file.
1//===-- CommandObjectRegister.cpp -----------------------------------------===//
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
10#include "lldb/Core/Debugger.h"
23#include "lldb/Target/Process.h"
26#include "lldb/Target/Thread.h"
27#include "lldb/Utility/Args.h"
30#include "llvm/Support/Errno.h"
31
32using namespace lldb;
33using namespace lldb_private;
34
35// "register read"
36#define LLDB_OPTIONS_register_read
37#include "CommandOptions.inc"
38
40public:
43 interpreter, "register read",
44 "Dump the contents of one or more register values from the current "
45 "frame. If no register is specified, dumps them all.",
46 nullptr,
47 eCommandRequiresFrame | eCommandRequiresRegContext |
48 eCommandProcessMustBeLaunched | eCommandProcessMustBePaused),
50 {{CommandArgumentType::eArgTypeFormat,
51 "Specify a format to be used for display. If this "
52 "is set, register fields will not be displayed."}}) {
54
55 // Add the "--format"
62 }
63
64 ~CommandObjectRegisterRead() override = default;
65
66 void
68 OptionElementVector &opt_element_vector) override {
70 return;
71 CommandObject::HandleArgumentCompletion(request, opt_element_vector);
72 }
73
74 Options *GetOptions() override { return &m_option_group; }
75
76 bool DumpRegister(const ExecutionContext &exe_ctx, Stream &strm,
77 RegisterContext &reg_ctx, const RegisterInfo &reg_info,
78 bool print_flags) {
79 RegisterValue reg_value;
80 if (!reg_ctx.ReadRegister(&reg_info, reg_value))
81 return false;
82
83 strm.Indent();
84
85 bool prefix_with_altname = (bool)m_command_options.alternate_name;
86 bool prefix_with_name = !prefix_with_altname;
87 DumpRegisterValue(reg_value, strm, reg_info, prefix_with_name,
88 prefix_with_altname, m_format_options.GetFormat(), 8,
89 exe_ctx.GetBestExecutionContextScope(), print_flags,
90 exe_ctx.GetTargetSP());
91 if ((reg_info.encoding == eEncodingUint) ||
92 (reg_info.encoding == eEncodingSint)) {
93 Process *process = exe_ctx.GetProcessPtr();
94 if (process && reg_info.byte_size == process->GetAddressByteSize()) {
95 addr_t reg_addr = reg_value.GetAsUInt64(LLDB_INVALID_ADDRESS);
96 if (reg_addr != LLDB_INVALID_ADDRESS) {
97 Address so_reg_addr;
99 reg_addr, so_reg_addr)) {
100 strm.PutCString(" ");
101 so_reg_addr.Dump(&strm, exe_ctx.GetBestExecutionContextScope(),
103 }
104 }
105 }
106 }
107 strm.EOL();
108 return true;
109 }
110
111 bool DumpRegisterSet(const ExecutionContext &exe_ctx, Stream &strm,
112 RegisterContext *reg_ctx, size_t set_idx,
113 bool primitive_only = false) {
114 uint32_t unavailable_count = 0;
115 uint32_t available_count = 0;
116
117 if (!reg_ctx)
118 return false; // thread has no registers (i.e. core files are corrupt,
119 // incomplete crash logs...)
120
121 const RegisterSet *const reg_set = reg_ctx->GetRegisterSet(set_idx);
122 if (reg_set) {
123 strm.Printf("%s:\n", (reg_set->name ? reg_set->name : "unknown"));
124 strm.IndentMore();
125 const size_t num_registers = reg_set->num_registers;
126 for (size_t reg_idx = 0; reg_idx < num_registers; ++reg_idx) {
127 const uint32_t reg = reg_set->registers[reg_idx];
128 const RegisterInfo *reg_info = reg_ctx->GetRegisterInfoAtIndex(reg);
129 // Skip the dumping of derived register if primitive_only is true.
130 if (primitive_only && reg_info && reg_info->value_regs)
131 continue;
132
133 if (reg_info && DumpRegister(exe_ctx, strm, *reg_ctx, *reg_info,
134 /*print_flags=*/false))
135 ++available_count;
136 else
137 ++unavailable_count;
138 }
139 strm.IndentLess();
140 if (unavailable_count) {
141 strm.Indent();
142 strm.Printf("%u registers were unavailable.\n", unavailable_count);
143 }
144 strm.EOL();
145 }
146 return available_count > 0;
147 }
148
149protected:
150 void DoExecute(Args &command, CommandReturnObject &result) override {
151 Stream &strm = result.GetOutputStream();
153
154 if (command.GetArgumentCount() == 0) {
155 size_t set_idx;
156
157 size_t num_register_sets = 1;
158 const size_t set_array_size = m_command_options.set_indexes.GetSize();
159 if (set_array_size > 0) {
160 for (size_t i = 0; i < set_array_size; ++i) {
161 set_idx =
162 m_command_options.set_indexes[i]->GetValueAs<uint64_t>().value_or(
163 UINT32_MAX);
164 if (set_idx < reg_ctx->GetRegisterSetCount()) {
165 if (!DumpRegisterSet(m_exe_ctx, strm, reg_ctx, set_idx)) {
166 if (errno)
167 result.AppendErrorWithFormatv("register read failed: {0}\n",
168 llvm::sys::StrError());
169 else
170 result.AppendError("unknown error while reading registers.\n");
171 break;
172 }
173 } else {
175 "invalid register set index: %" PRIu64 "\n", (uint64_t)set_idx);
176 break;
177 }
178 }
179 } else {
181 num_register_sets = reg_ctx->GetRegisterSetCount();
182
183 for (set_idx = 0; set_idx < num_register_sets; ++set_idx) {
184 // When dump_all_sets option is set, dump primitive as well as
185 // derived registers.
186 DumpRegisterSet(m_exe_ctx, strm, reg_ctx, set_idx,
188 }
189 }
190 } else {
192 result.AppendError("the --all option can't be used when registers "
193 "names are supplied as arguments\n");
194 } else if (m_command_options.set_indexes.GetSize() > 0) {
195 result.AppendError("the --set <set> option can't be used when "
196 "registers names are supplied as arguments\n");
197 } else {
198 for (auto &entry : command) {
199 // in most LLDB commands we accept $rbx as the name for register RBX
200 // - and here we would reject it and non-existant. we should be more
201 // consistent towards the user and allow them to say reg read $rbx -
202 // internally, however, we should be strict and not allow ourselves
203 // to call our registers $rbx in our own API
204 auto arg_str = entry.ref();
205 arg_str.consume_front("$");
206
207 if (const RegisterInfo *reg_info =
208 reg_ctx->GetRegisterInfoByName(arg_str)) {
209 // If they have asked for a specific format don't obscure that by
210 // printing flags afterwards.
211 bool print_flags =
213 if (!DumpRegister(m_exe_ctx, strm, *reg_ctx, *reg_info,
214 print_flags))
215 strm.Printf("%-12s = error: unavailable\n", reg_info->name);
216 } else {
217 result.AppendErrorWithFormat("Invalid register name '%s'.\n",
218 arg_str.str().c_str());
219 }
220 }
221 }
222 }
223 }
224
226 public:
228 : set_indexes(OptionValue::ConvertTypeToMask(OptionValue::eTypeUInt64)),
229 dump_all_sets(false, false), // Initial and default values are false
230 alternate_name(false, false) {}
231
232 ~CommandOptions() override = default;
233
234 llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
235 return llvm::ArrayRef(g_register_read_options);
236 }
237
238 void OptionParsingStarting(ExecutionContext *execution_context) override {
242 }
243
244 Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
245 ExecutionContext *execution_context) override {
247 const int short_option = GetDefinitions()[option_idx].short_option;
248 switch (short_option) {
249 case 's': {
250 OptionValueSP value_sp(OptionValueUInt64::Create(option_value, error));
251 if (value_sp)
252 set_indexes.AppendValue(value_sp);
253 } break;
254
255 case 'a':
256 // When we don't use OptionValue::SetValueFromCString(const char *) to
257 // set an option value, it won't be marked as being set in the options
258 // so we make a call to let users know the value was set via option
261 break;
262
263 case 'A':
264 // When we don't use OptionValue::SetValueFromCString(const char *) to
265 // set an option value, it won't be marked as being set in the options
266 // so we make a call to let users know the value was set via option
269 break;
270
271 default:
272 llvm_unreachable("Unimplemented option");
273 }
274 return error;
275 }
276
277 // Instance variables to hold the values for command options.
281 };
282
286};
287
288// "register write"
290public:
292 : CommandObjectParsed(interpreter, "register write",
293 "Modify a single register value.", nullptr,
294 eCommandRequiresFrame | eCommandRequiresRegContext |
295 eCommandProcessMustBeLaunched |
296 eCommandProcessMustBePaused) {
299 CommandArgumentData register_arg;
300 CommandArgumentData value_arg;
301
302 // Define the first (and only) variant of this arg.
303 register_arg.arg_type = eArgTypeRegisterName;
304 register_arg.arg_repetition = eArgRepeatPlain;
305
306 // There is only one variant this argument could be; put it into the
307 // argument entry.
308 arg1.push_back(register_arg);
309
310 // Define the first (and only) variant of this arg.
311 value_arg.arg_type = eArgTypeValue;
313
314 // There is only one variant this argument could be; put it into the
315 // argument entry.
316 arg2.push_back(value_arg);
317
318 // Push the data for the first argument into the m_arguments vector.
319 m_arguments.push_back(arg1);
320 m_arguments.push_back(arg2);
321 }
322
323 ~CommandObjectRegisterWrite() override = default;
324
325 void
327 OptionElementVector &opt_element_vector) override {
328 if (!m_exe_ctx.HasProcessScope() || request.GetCursorIndex() != 0)
329 return;
330
333 }
334
335protected:
336 void DoExecute(Args &command, CommandReturnObject &result) override {
337 DataExtractor reg_data;
339
340 if (command.GetArgumentCount() != 2) {
341 result.AppendError(
342 "register write takes exactly 2 arguments: <reg-name> <value>");
343 } else {
344 auto reg_name = command[0].ref();
345 auto value_str = command[1].ref();
346
347 // in most LLDB commands we accept $rbx as the name for register RBX -
348 // and here we would reject it and non-existant. we should be more
349 // consistent towards the user and allow them to say reg write $rbx -
350 // internally, however, we should be strict and not allow ourselves to
351 // call our registers $rbx in our own API
352 reg_name.consume_front("$");
353
354 const RegisterInfo *reg_info = reg_ctx->GetRegisterInfoByName(reg_name);
355
356 if (reg_info) {
357 RegisterValue reg_value;
358
359 Status error(reg_value.SetValueFromString(reg_info, value_str));
360 if (error.Success()) {
361 if (reg_ctx->WriteRegister(reg_info, reg_value)) {
362 // Toss all frames and anything else in the thread after a register
363 // has been written.
366 return;
367 }
368 }
369 if (error.AsCString()) {
371 "Failed to write register '%s' with value '%s': %s\n",
372 reg_name.str().c_str(), value_str.str().c_str(),
373 error.AsCString());
374 } else {
376 "Failed to write register '%s' with value '%s'",
377 reg_name.str().c_str(), value_str.str().c_str());
378 }
379 } else {
380 result.AppendErrorWithFormat("Register not found for '%s'.\n",
381 reg_name.str().c_str());
382 }
383 }
384 }
385};
386
387// "register info"
389public:
391 : CommandObjectParsed(interpreter, "register info",
392 "View information about a register.", nullptr,
393 eCommandRequiresFrame | eCommandRequiresRegContext |
394 eCommandProcessMustBeLaunched |
395 eCommandProcessMustBePaused) {
396 SetHelpLong(R"(
397Name The name lldb uses for the register, optionally with an alias.
398Size The size of the register in bytes and again in bits.
399Invalidates (*) The registers that would be changed if you wrote this
400 register. For example, writing to a narrower alias of a wider
401 register would change the value of the wider register.
402Read from (*) The registers that the value of this register is constructed
403 from. For example, a narrower alias of a wider register will be
404 read from the wider register.
405In sets (*) The register sets that contain this register. For example the
406 PC will be in the "General Purpose Register" set.
407Fields (*) A table of the names and bit positions of the values contained
408 in this register.
409
410Fields marked with (*) may not always be present. Some information may be
411different for the same register when connected to different debug servers.)");
412
414 }
415
416 ~CommandObjectRegisterInfo() override = default;
417
418 void
420 OptionElementVector &opt_element_vector) override {
421 if (!m_exe_ctx.HasProcessScope() || request.GetCursorIndex() != 0)
422 return;
423 CommandObject::HandleArgumentCompletion(request, opt_element_vector);
424 }
425
426protected:
427 void DoExecute(Args &command, CommandReturnObject &result) override {
428 if (command.GetArgumentCount() != 1) {
429 result.AppendError("register info takes exactly 1 argument: <reg-name>");
430 return;
431 }
432
433 llvm::StringRef reg_name = command[0].ref();
435 const RegisterInfo *reg_info = reg_ctx->GetRegisterInfoByName(reg_name);
436 if (reg_info) {
438 result.GetOutputStream(), *reg_ctx, *reg_info,
439 GetCommandInterpreter().GetDebugger().GetTerminalWidth());
441 } else
442 result.AppendErrorWithFormat("No register found with name '%s'.\n",
443 reg_name.str().c_str());
444 }
445};
446
447// CommandObjectRegister constructor
449 : CommandObjectMultiword(interpreter, "register",
450 "Commands to access registers for the current "
451 "thread and stack frame.",
452 "register [read|write|info] ...") {
453 LoadSubCommand("read",
455 LoadSubCommand("write",
457 LoadSubCommand("info",
459}
460
static llvm::raw_ostream & error(Stream &strm)
void DoExecute(Args &command, CommandReturnObject &result) override
~CommandObjectRegisterInfo() override=default
void HandleArgumentCompletion(CompletionRequest &request, OptionElementVector &opt_element_vector) override
The default version handles argument definitions that have only one argument type,...
CommandObjectRegisterInfo(CommandInterpreter &interpreter)
Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_value, ExecutionContext *execution_context) override
void OptionParsingStarting(ExecutionContext *execution_context) override
llvm::ArrayRef< OptionDefinition > GetDefinitions() override
bool DumpRegisterSet(const ExecutionContext &exe_ctx, Stream &strm, RegisterContext *reg_ctx, size_t set_idx, bool primitive_only=false)
void HandleArgumentCompletion(CompletionRequest &request, OptionElementVector &opt_element_vector) override
The default version handles argument definitions that have only one argument type,...
~CommandObjectRegisterRead() override=default
bool DumpRegister(const ExecutionContext &exe_ctx, Stream &strm, RegisterContext &reg_ctx, const RegisterInfo &reg_info, bool print_flags)
CommandObjectRegisterRead(CommandInterpreter &interpreter)
void DoExecute(Args &command, CommandReturnObject &result) override
void HandleArgumentCompletion(CompletionRequest &request, OptionElementVector &opt_element_vector) override
The default version handles argument definitions that have only one argument type,...
~CommandObjectRegisterWrite() override=default
void DoExecute(Args &command, CommandReturnObject &result) override
CommandObjectRegisterWrite(CommandInterpreter &interpreter)
A section + offset based address class.
Definition: Address.h:62
@ DumpStyleResolvedDescription
Display the details about what an address resolves to.
Definition: Address.h:104
bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style, DumpStyle fallback_style=DumpStyleInvalid, uint32_t addr_byte_size=UINT32_MAX, bool all_ranges=false, std::optional< Stream::HighlightSettings > settings=std::nullopt) const
Dump a description of this object to a Stream.
Definition: Address.cpp:408
A command line argument class.
Definition: Args.h:33
size_t GetArgumentCount() const
Gets the number of arguments left in this command object.
Definition: Args.h:116
static bool InvokeCommonCompletionCallbacks(CommandInterpreter &interpreter, uint32_t completion_mask, lldb_private::CompletionRequest &request, SearchFilter *searcher)
bool LoadSubCommand(llvm::StringRef cmd_name, const lldb::CommandObjectSP &command_obj) override
CommandObjectRegister(CommandInterpreter &interpreter)
std::vector< CommandArgumentData > CommandArgumentEntry
virtual void SetHelpLong(llvm::StringRef str)
void AddSimpleArgumentList(lldb::CommandArgumentType arg_type, ArgumentRepetitionType repetition_type=eArgRepeatPlain)
ExecutionContext m_exe_ctx
std::vector< CommandArgumentEntry > m_arguments
CommandInterpreter & GetCommandInterpreter()
virtual void HandleArgumentCompletion(CompletionRequest &request, OptionElementVector &opt_element_vector)
The default version handles argument definitions that have only one argument type,...
void AppendErrorWithFormatv(const char *format, Args &&... args)
void void AppendError(llvm::StringRef in_string)
void SetStatus(lldb::ReturnStatus status)
void AppendErrorWithFormat(const char *format,...) __attribute__((format(printf
"lldb/Utility/ArgCompletionRequest.h"
An data extractor class.
Definition: DataExtractor.h:48
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
bool HasProcessScope() const
Returns true the ExecutionContext object contains a valid target and process.
ExecutionContextScope * GetBestExecutionContextScope() const
const lldb::TargetSP & GetTargetSP() const
Get accessor to get the target shared pointer.
Target & GetTargetRef() const
Returns a reference to the target object.
Process * GetProcessPtr() const
Returns a pointer to the process object.
Thread & GetThreadRef() const
Returns a reference to the thread object.
RegisterContext * GetRegisterContext() const
static const uint32_t OPTION_GROUP_GDB_FMT
static const uint32_t OPTION_GROUP_FORMAT
OptionValueFormat & GetFormatValue()
void Append(OptionGroup *group)
Append options from a OptionGroup class.
Definition: Options.cpp:755
bool AppendValue(const lldb::OptionValueSP &value_sp)
static lldb::OptionValueSP Create(llvm::StringRef value_str, Status &error)
std::optional< T > GetValueAs() const
Definition: OptionValue.h:273
A command line option parsing protocol class.
Definition: Options.h:58
A plug-in interface definition class for debugging a process.
Definition: Process.h:341
uint32_t GetAddressByteSize() const
Definition: Process.cpp:3600
virtual const RegisterSet * GetRegisterSet(size_t reg_set)=0
virtual const RegisterInfo * GetRegisterInfoAtIndex(size_t reg)=0
virtual bool WriteRegister(const RegisterInfo *reg_info, const RegisterValue &reg_value)=0
virtual size_t GetRegisterSetCount()=0
const RegisterInfo * GetRegisterInfoByName(llvm::StringRef reg_name, uint32_t start_idx=0)
virtual bool ReadRegister(const RegisterInfo *reg_info, RegisterValue &reg_value)=0
Status SetValueFromString(const RegisterInfo *reg_info, llvm::StringRef value_str)
uint64_t GetAsUInt64(uint64_t fail_value=UINT64_MAX, bool *success_ptr=nullptr) const
bool ResolveLoadAddress(lldb::addr_t load_addr, Address &so_addr, bool allow_section_end=false) const
An error handling class.
Definition: Status.h:44
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
size_t Indent(llvm::StringRef s="")
Indent the current line in the stream.
Definition: Stream.cpp:157
size_t Printf(const char *format,...) __attribute__((format(printf
Output printf formatted output to the stream.
Definition: Stream.cpp:134
size_t PutCString(llvm::StringRef cstr)
Output a C string to the stream.
Definition: Stream.cpp:65
size_t EOL()
Output and End of Line character to the stream.
Definition: Stream.cpp:155
void IndentLess(unsigned amount=2)
Decrement the current indentation level.
Definition: Stream.cpp:198
void IndentMore(unsigned amount=2)
Increment the current indentation level.
Definition: Stream.cpp:195
SectionLoadList & GetSectionLoadList()
Definition: Target.h:1143
#define UINT64_MAX
Definition: lldb-defines.h:23
#define LLDB_OPT_SET_ALL
Definition: lldb-defines.h:110
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:82
#define UINT32_MAX
Definition: lldb-defines.h:19
A class that represents a running process on the host machine.
std::vector< OptionArgElement > OptionElementVector
Definition: Options.h:43
void DumpRegisterInfo(Stream &strm, RegisterContext &ctx, const RegisterInfo &info, uint32_t terminal_width)
void DumpRegisterValue(const RegisterValue &reg_val, Stream &s, const RegisterInfo &reg_info, bool prefix_with_name, bool prefix_with_alt_name, lldb::Format format, uint32_t reg_name_right_align_at=0, ExecutionContextScope *exe_scope=nullptr, bool print_flags=false, lldb::TargetSP target_sp=nullptr)
Definition: SBAddress.h:15
@ eRegisterCompletion
std::shared_ptr< lldb_private::CommandObject > CommandObjectSP
Definition: lldb-forward.h:331
@ eEncodingUint
unsigned integer
@ eEncodingSint
signed integer
@ eReturnStatusSuccessFinishResult
@ eReturnStatusSuccessFinishNoResult
@ eArgTypeRegisterName
uint64_t addr_t
Definition: lldb-types.h:80
std::shared_ptr< lldb_private::OptionValue > OptionValueSP
Definition: lldb-forward.h:382
Used to build individual command argument lists.
Definition: CommandObject.h:93
Every register is described in detail including its name, alternate name (optional),...
lldb::Encoding encoding
Encoding of the register bits.
uint32_t * value_regs
List of registers (terminated with LLDB_INVALID_REGNUM).
uint32_t byte_size
Size in bytes of the register.
Registers are grouped into register sets.
size_t num_registers
The number of registers in REGISTERS array below.
const uint32_t * registers
An array of register indices in this set.
const char * name
Name of this register set.