Gdb.h

#ifndef ROSE_BinaryAnalysis_Debugger_Gdb_H
#define ROSE_BinaryAnalysis_Debugger_Gdb_H
#include <featureTests.h>
#ifdef ROSE_ENABLE_DEBUGGER_GDB
#include <Rose/BinaryAnalysis/Debugger/Base.h>
 
#include <Rose/BinaryAnalysis/AddressIntervalSet.h>
#include <Rose/BinaryAnalysis/Debugger/GdbResponse.h>
#include <Rose/Yaml.h>
 
#include <boost/asio.hpp>
#include <boost/filesystem.hpp>
#include <boost/process.hpp>
 
#include <condition_variable>
#include <future>
#include <string>
#include <thread>
 
namespace Rose {
namespace BinaryAnalysis {
namespace Debugger {
 
class Gdb: public Base {
 
    // Types
public:
    using Ptr = GdbPtr;
 
    class Specimen {
    public:
        struct Remote {
            std::string host = "localhost";             
            uint16_t port = 1234;                       
        };
 
    private:
        boost::filesystem::path gdbName_ = "gdb-multiarch"; // name of the GDB executable
        boost::filesystem::path executable_;                // optional name of executable containing symbols
        Remote remote_;                                     // how to connect to the GDB server
 
    public:
        Specimen();
 
        Specimen(const boost::filesystem::path &exeName);
 
        Specimen(const boost::filesystem::path &exeName, const std::string &host, uint16_t port);
 
    public:
        const boost::filesystem::path &gdbName() const;
        void gdbName(const boost::filesystem::path&);
        const boost::filesystem::path& executable() const;
        void executable(const boost::filesystem::path&);
        const Remote& remote() const;
        void remote(const Remote&);
        void remote(const std::string &host, uint16_t port);
        void print(std::ostream&) const;
 
        std::string toString() const;
    };
 
    // Thread-safe FIFO
    template<class T>
    class Fifo {
    public:
        using Value = T;
 
    private:
        std::condition_variable cond_;                  // notified by append()
        std::mutex mutex_;                              // protects the following data members
        std::list<Value> items_;
        bool isClosed_ = false;
 
    public:
        // Append an item to the list
        void append(const Value &item) {
            const std::lock_guard<std::mutex> lock(mutex_);
            items_.push_back(item);
            cond_.notify_one();
        }
 
        // Remove all items from this FIFO
        void clear() {
            const std::lock_guard<std::mutex> lock(mutex_);
            items_.clear();
            cond_.notify_all();
        }
 
        // Mark the list as closed. No more items can be appended.
        void close() {
            {
                const std::lock_guard<std::mutex> lock(mutex_);
                isClosed_ = true;
            }
            cond_.notify_all();
        }
 
        // Returns the item from the queue, if any.
        Sawyer::Optional<Value> nonblockingNext() {
            const std::lock_guard<std::mutex> lock(mutex_);
            if (items_.empty()) {
                return Sawyer::Nothing();
            } else {
                Value item = items_.front();
                items_.pop_front();
                return item;
            }
        }
 
        // Blocks until an item can be returned or the queue is closed
        Sawyer::Optional<Value> blockingNext() {
            std::unique_lock<std::mutex> lock(mutex_);
            while (items_.empty() && !isClosed_)
                cond_.wait(lock);
            if (items_.empty()) {
                return Sawyer::Nothing();
            } else {
                Value item = items_.front();
                items_.pop_front();
                return item;
            }
        }
 
        // Remvoe all items
        void reset() {
            std::lock_guard<std::mutex> lock(mutex_);
            items_.clear();
            isClosed_ = false;
        }
    };
 
    // GDB command response record
    struct Response {
        bool hasEndMarker = false;
 
        struct ResultRecord {
            enum ResultClass { EMPTY, DONE, RUNNING, CONNECTED, ERROR, EXIT };
            ResultClass rclass = EMPTY;
            std::string token;
            std::list<Yaml::Node> results;
        };
 
        std::list<ResultRecord> resultRecord;
    };
 
    // A register descriptor or just a size in bits.
    class RegInfo {
        RegisterDescriptor reg_;                        // might be invalid (default constructed, false)
        size_t nBits_ = 0;                              // valid only if `reg` is invalid
    public:
        explicit RegInfo(RegisterDescriptor);
        explicit RegInfo(size_t);
        RegisterDescriptor reg() const;
        size_t nBits() const;
    };
 
    // Data members
private:
    std::thread gdbThread_;
    Fifo<std::string> gdbOutput_;
    boost::asio::io_context ioctx_;
    boost::process::async_pipe gdbOutputPipe_;
    boost::process::opstream gdbInput_;
    boost::asio::streambuf gdbOutputBuffer_;
    std::vector<std::pair<std::string, RegInfo>> registers_;    // info about registers obtained from GDB; some entries empty
    std::list<GdbResponse> responses_;                          // accumulated responses
    AddressIntervalSet breakPoints_;                            // all break points
    std::map<Address, unsigned /*bp_id*/> gdbBreakPoints_;      // subset of breakpoints known to GDB
    std::future<int> exitCodeFuture_;                           // exit code returned from GDB thread
    Sawyer::Optional<int> exitCode_;                            // exit code from the GDB process
#ifdef NDEBUG
    bool checkWrites_ = false;                                  // perform a read after each write to verify what we wrote
#else
    bool checkWrites_ = true;
#endif
 
    // Constructors and destructors
protected:
    Gdb();
public:
    ~Gdb();
 
public:
    static Ptr instance();
 
    static Ptr instance(const Specimen&);
 
    // Properties
public:
    bool checkWrites() const;
    void checkWrites(bool);
    // Attaching and detaching
public:
    virtual void attach(const Specimen&);
 
    // Low-level stuff not often used publically but available nonetheless.
public:
    const std::list<GdbResponse>& sendCommand(const std::string&);
 
    std::list<GdbResponse> readRequiredResponses();
 
    std::list<GdbResponse> readOptionalResponses();
 
    const std::list<GdbResponse>& responses() const;
 
    void resetResponses();
 
    const std::vector<std::pair<std::string, RegInfo>>& registerNames() const;
 
    // Overrides for methods declared and documented in the super class.
public:
    virtual bool isAttached() override;
    virtual void detach() override;
    virtual void terminate() override;
    virtual std::vector<ThreadId> threadIds() override;
    virtual void setBreakPoint(const AddressInterval&) override;
    virtual void setBreakPoints(const AddressIntervalSet&) override;
    virtual AddressIntervalSet breakPoints() override;
    virtual void clearBreakPoint(const AddressInterval&) override;
    virtual void clearBreakPoints() override;
    virtual void singleStep(ThreadId) override;
    virtual void runToBreakPoint(ThreadId) override;
    virtual Sawyer::Container::BitVector readRegister(ThreadId, RegisterDescriptor) override;
    virtual std::vector<RegisterDescriptor> availableRegisters() override;
    virtual void writeRegister(ThreadId, RegisterDescriptor, const Sawyer::Container::BitVector&) override;
    virtual void writeRegister(ThreadId, RegisterDescriptor, uint64_t value) override;
    virtual size_t readMemory(Address va, size_t nBytes, uint8_t *buffer) override;
    virtual std::vector<uint8_t> readMemory(Address va, size_t nBytes) override;
    virtual Sawyer::Container::BitVector readMemory(Address va, size_t nBytes, ByteOrder::Endianness order) override;
    virtual size_t writeMemory(Address va, size_t nBytes, const uint8_t *bytes) override;
    virtual bool isTerminated() override;
    virtual std::string howTerminated() override;
    virtual Sawyer::Container::BitVector readAllRegisters(ThreadId) override;
    virtual void writeAllRegisters(ThreadId, const Sawyer::Container::BitVector&) override;
 
    // Supporting functions
private:
    // Read GDB's multi-line response to a command
    std::list<GdbResponse> readResponseSet(bool required);
 
    // Find the index for the GDB register whose major and minor numbers match the specified register.
    Sawyer::Optional<size_t> findRegisterIndex(RegisterDescriptor) const;
 
    // Find the register descriptor for the GDB register whose major and minor numbers match the specified register. Returns an
    // empty descriptor if not found.
    RegisterDescriptor findRegister(RegisterDescriptor) const;
 
    // True if GDB should handle the break points; false if ROSE should handle the break points.
    bool gdbHandlesBreakPoints() const;
 
    // Parse a result from -data-list-register-values. Specifically, the command returns a vector of objects each of which has
    // a "number" and a "value" field. The number is the GDB register index, and the "value" is the string that this function
    // is attempting to parse. The value (assuming the first argument to the command was "x") is either a hexadecimal string
    // of arbitrary length, or a string that starts with "{uint<N> = <HEX>," where "<N>" is the number of bits and "<HEX>" is
    // the string this function returns.
    std::string parseDataListRegisterValuesValue(const std::string&);
 
    // Read a register according to its GDB index.
    Sawyer::Container::BitVector readRegisterIndexed(ThreadId, size_t);
};
 
std::ostream& operator<<(std::ostream&, const Gdb::Specimen&);
 
} // namespace
} // namespace
} // namespace
 
#endif
#endif