Skip to content
This repository has been archived by the owner on Jul 22, 2020. It is now read-only.

runner.reference

Jump to bottom
Klemens Morgenstern edited this page Apr 4, 2018 · 1 revision

Summary

Members Descriptions
void metal_dbg_setup_bps
(std::vector<std::unique_ptr<metal::debug::break_point >> & bps) 		This function is the central function needed to provide a break-point plugin.
void metal_dbg_setup_options<br>(boost::program_options::options_description & po) This function can be used to add program options for the plugin.
namespace metal::debug

Members

void metal_dbg_setup_bps(std::vector<std::unique_ptr<metal::debug::break_point >> & bps)

This function is the central function needed to provide a break-point plugin.

void metal_dbg_setup_options(boost::program_options::options_description & po)

This function can be used to add program options for the plugin.

namespace metal::debug

Summary

Members Descriptions
class metal::debug::break_point This class is used to implement a break_point, i.e. is inherited by an implementation.
class metal::debug::interpreter
class metal::debug::process
struct metal::debug::address_info Information about a certain address in the program, i.e in source code.
struct metal::debug::arg This type represents an argument passed to a function. It inherits var and adds the parameter identifier.
struct metal::debug::backtrace_elem This class represents an entry in the backtrace.
struct metal::debug::cstring_t This function represents a null-terminated string in gdb. Gdb can add a display for a c-string if a char* is passed to a function.
struct metal::debug::frame This class represents a stackframe. A stackframe let's you examine the stack in gdb. A reference to the frame will be passed to the break-point implementation on invocation.
struct metal::debug::interpreter_error
struct metal::debug::location Simple structure representing a location in code.
struct metal::debug::var This type represents a variable in gdb, as given by frame::print or frame::call.

class metal::debug::break_point

This class is used to implement a break_point, i.e. is inherited by an implementation.

Summary

Members Descriptions
const std::string & identifier() const Returns the identifier string, either the functions name or the location.
const boost::optional< std::string > & condition() Return the condition of the breakpoint.
break_point(const std::string & func_name) Construct the breakpoint from a function identifier. The function signature can either be the pure name of the function, which will yield several breakpoints or you can be an explicit overload.
break_point(const std::string & file_name,std::size_t line) Construct a breakpoint from a location in source-code.
void invoke(frame & fr,const std::string & file,int line) This function will be called when the breakpoint is reached.
virtual void set_at(std::uint64_t addr,const std::string & file,int line) This function is called when the breakpoint is set once. It is meant to be overridden, this functions is empty.
virtual void set_multiple(std::uint64_t addr,std::string & name,int cnt) This function is called when the breakpoint is set multiple times. It is meant to be overridden, this functions is empty.
virtual void set_not_found() This function is called when the breakpoint target could not be found. It is meant to be overridden, this functions is empty.
void set_condition(const std::string & condition) Add a condition for this breakpoint.
virtual ~break_point() = default Destructor.

Members

const std::string & identifier() const

Returns the identifier string, either the functions name or the location.

const boost::optional< std::string > & condition()

Return the condition of the breakpoint.

break_point(const std::string & func_name)

Construct the breakpoint from a function identifier. The function signature can either be the pure name of the function, which will yield several breakpoints or you can be an explicit overload.

If you want to define the overload, the full type names must be used, not the aliases. E.g. for function void foo(std::string &); func_name must be foo(std::basic_string<char, std::char_traits<char>, std::allocator<char>>&).

Parameters

  • func_name The Identifier.

break_point(const std::string & file_name,std::size_t line)

Construct a breakpoint from a location in source-code.

Parameters

  • file_name The name of the source file.

  • line The line of the breakpoint in the source file

void invoke(frame & fr, const std::string & file,int line)

This function will be called when the breakpoint is reached.

Parameters

  • fr The data frame of the breakpoint.

  • file The file the breakpoint is in.

  • line The line in the file.

virtual void set_at(std::uint64_t addr,const std::string & file,int line)

This function is called when the breakpoint is set once. It is meant to be overridden, this functions is empty.

Parameters

  • addr The address of the location in the binary

  • file The file the breakpoint is in

  • line The line of the breakpoint in the file.

virtual void set_multiple(std::uint64_t addr,std::string & name,int cnt)

This function is called when the breakpoint is set multiple times. It is meant to be overridden, this functions is empty.

Parameters

  • addr The address of the location in the binary.

  • name The name of the breakpoint.

  • cnt Number of breakpoints set.

virtual void set_not_found()

This function is called when the breakpoint target could not be found. It is meant to be overridden, this functions is empty.

void set_condition(const std::string & condition)

Add a condition for this breakpoint.

Parameters

  • condition A code snippet for the breakpoint condition.

virtual ~break_point() = default

Destructor.

class metal::debug::interpreter

Summary

Members Descriptions
interpreter() = default`
virtual ~interpreter() = default

class metal::debug::process

Summary

Members Descriptions
void set_init_script(std::vector< std::string > && init_scripts)
void set_init_scripts(const std::vector< std::string > & init_scripts)
bool running()
void set_exit(int code)
void set_program(const std::string & program)
void set_args(const std::vector< std::string > & args)
void set_remote(const std::string & remote)
void enable_debug()
std::ostream & log()
process(const boost::filesystem::path & gdb,const std::string & exe,const std::vector< std::string > & args)
virtual ~process() = default
int exit_code()
void set_log(const std::string & name)
void set_timeout(int value)
void add_break_point(std::unique_ptr< break_point > && ptr)
void add_break_points(std::vector< std::unique_ptr< break_point >> && ptrs)
virtual void run()

struct metal::debug::address_info

Information about a certain address in the program, i.e in source code.

Summary

Members Descriptions
std::string file The name of the file the code was generated from.
std::size_t line The line in the file.
boost::optional<std::string> full_name The absolute path of the file.
boost::optional<std::string> function The function this piece of code is part of.
boost::optional<std::uint64_t> offset The offset in the containing function, if available.

struct metal::debug::arg 

struct metal::debug::arg
  : public metal::debug::var

This type represents an argument passed to a function. It inherits var and adds the parameter identifier.

Summary

Members Descriptions
std::string id The identifier of the parameter.

struct metal::debug::backtrace_elem

This class represents an entry in the backtrace.

Summary

Members Descriptions
int cnt The position in the backtrace.
boost::optional<std::uint64_t> addr Gives the position the functions.
std::string func The name of the functions.
location loc Location of the function called.

struct metal::debug::cstring_t

This function represents a null-terminated string in gdb. Gdb can add a display for a c-string if a char* is passed to a function.

GDB can shorten the string and add an ellipsis at the end.

Summary

Members Descriptions
std::string value
bool ellipsis The cstring value extracted from the gdb output.

Members

struct metal::debug::frame

This class represents a stackframe. A stackframe let's you examine the stack in gdb. A reference to the frame will be passed to the break-point implementation on invocation.

For more details have a look at the gdb documentation.

Summary

Members Descriptions
const std::string & id() const Get the id of the current frame.
const std::vector< arg > & arg_list() const Get the already read argument list. This means it does not need to be read again.
const arg & arg_list(std::size_t index) const
boost::optional<[address_info](#struct-metaldebugaddress_info)> addr2line(std::uint64_t addr) const Examine the program at the given address.
std::string get_cstring(std::size_t index) This function returns the cstring of the argument requested, if it is a null-terminated string. This will take care of the possible ellipsis of passed cstrings.
std::unordered_map<std::string, std::uint64_t> regs() Returns the map of the registers and their values.
void set(const std::string & var,const std::string & val) Set a variable in the current frame.
void set(const std::string & var,std::size_t idx,const std::string & val) Set a member of an array in the current frame.
boost::optional<var> call(const std::string & cl) Call a function in the current frame. If not void the return value holds an instance of gdb::var.
var print(const std::string & id,bool bitwise)` Print the value of a symbol in the current frame.
void return_(const std::string & value) Return from the current function.
void set_exit(int code) Sets the program to have exited. This is necessary for embedded environments where there is no operating system.
void select(int frame) This function switches the current frame. The frame of the break-point location is zero, while adding one is always the next outer frame i.e. function call.
std::vector<backtrace_elem > backtrace() This function returns the backtrace of the current position.
std::ostream & log() This function allows access to the log sink of the gdb-runner.
class interpreter & interpreter() Gives a reference to the interpreter.
void disable(const break_point & bp) Disable a breakpoint.
void enable(const break_point & bp) Reenable a breakpoint.
std::vector<std::uint8_t> read_memory(std::uint64_t addr,std::size_t size) Read a chunk of memory.
void write_memory(std::uint64_t addr,const std::vector< std::uint8_t > & vec) Write a chunk of memory.

Members

const std::string & id() const

Get the id of the current frame.

const std::vector< arg > & arg_list() const

Get the already read argument list. This means it does not need to be read again.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function is for convenience and let's the user access elements in the argument list.

Parameters

  • index The index for the element.

const arg & arg_list(std::size_t index) const

boost::optional<address_info> addr2line(std::uint64_t addr) const

Examine the program at the given address.

Returns

Only returns a set value, if the address is in the right space.

std::string get_cstring(std::size_t index)

This function returns the cstring of the argument requested, if it is a null-terminated string. This will take care of the possible ellipsis of passed cstrings.

Parameters

  • index Position of the argument the cstring shall be obtained from.

std::unordered_map<std::string, std::uint64_t> regs()

Returns the map of the registers and their values.

void set(const std::string & var,const std::string & val)

Set a variable in the current frame.

void set(const std::string & var,std::size_t idx,const std::string & val)

Set a member of an array in the current frame.

boost::optional<var> call(const std::string & cl)

Call a function in the current frame. If not void the return value holds an instance of gdb::var.

var print(const std::string & id,bool bitwise)

Print the value of a symbol in the current frame.

Parameters

  • id The name of the symbol

  • bitwise If set true, the value will be printed as an array of binary values.

Returns

The printed value

void return_(const std::string & value)

Return from the current function.

Parameters

  • value The return value, needs to be passed if the return is not void.

void set_exit(int code)

Sets the program to have exited. This is necessary for embedded environments where there is no operating system.

Do only use it in an embedded environment.

Parameters

  • code The exit code.

void select(int frame)

This function switches the current frame. The frame of the break-point location is zero, while adding one is always the next outer frame i.e. function call.

Example

void foo()
{
}

void bar()
{
   int value = 42;
   foo();
}

If the breakpoint is in foo(), selecting frame 1, will yield the frame of bar. E.g.:

void invoke(frame &fr)
{
   fr.select(1); //select bar
   auto val = fr.print("value");
   assert(val.value == "42");
}

Parameters

  • frame The frame to be selected.

std::vector< backtrace_elem > backtrace()`

This function returns the backtrace of the current position.

See also: The the gdb documentation for more details.

Returns

A vector of the backtrace elements.

std::ostream & log()

This function allows access to the log sink of the gdb-runner.

class interpreter & interpreter()

Gives a reference to the interpreter.

void disable(const break_point & bp)

Disable a breakpoint.

void enable(const break_point & bp)

Reenable a breakpoint.

std::vector<std::uint8_t> read_memory(std::uint64_t addr,std::size_t size)

Read a chunk of memory.

void write_memory(std::uint64_t addr,const std::vector< std::uint8_t > & vec)

Write a chunk of memory.

struct metal::debug::interpreter_error 

struct metal::debug::interpreter_error
  : public runtime_error

Summary

Members Descriptions

Members

struct metal::debug::location

Simple structure representing a location in code.

Summary

Members Descriptions
std::string file The file the location is in.
int line The line in the file.

Members

std::string file

The file the location is in.

int line

The line in the file.

struct metal::debug::var

This type represents a variable in gdb, as given by frame::print or frame::call.

Summary

Members Descriptions
boost::optional<std::uint64_t> ref
std::string value The address of the target the value is a reference.
cstring_t cstring The value as cstring if available.

The address of the target the value is a reference.

The actually value

cstring_tcstring

The value as cstring if available.

Clone this wiki locally