Linux.h

#ifndef ROSE_BinaryAnalysis_Debugger_Linux_H
#define ROSE_BinaryAnalysis_Debugger_Linux_H
#include <featureTests.h>
#ifdef ROSE_ENABLE_DEBUGGER_LINUX

#include <Rose/BinaryAnalysis/Debugger/Base.h>

#include <Sawyer/Optional.h>

namespace Rose {
namespace BinaryAnalysis {
namespace Debugger {

class Linux: public Base {
    // Types
public:
    using Ptr = LinuxPtr;

    enum class DetachMode {
        KILL,                                           
        DETACH,                                         
        CONTINUE,                                       
        NOTHING                                         
    };

    enum class Flag {
        ATTACH          = 0x00000001,                   
        REDIRECT_INPUT  = 0x00000002,                   
        REDIRECT_OUTPUT = 0x00000004,                   
        REDIRECT_ERROR  = 0x00000008,                   
        CLOSE_FILES     = 0x00000010,                   
        DEFAULT_FLAGS   = 0x00000013                    
    };

    class Specimen {
        BitFlags<Flag> flags_;                          // operational flags
        unsigned long persona_;                         // personality(2) flags

        // Members for running a program
        boost::filesystem::path program_;               // full path of executable program
        std::vector<std::string> arguments_;            // command-line arguments of executable program
        boost::filesystem::path workingDirectory_;      // name or working directory, or use CWD if empty
        std::vector<boost::regex> clearEnvVars_;        // clear environment variables matching these patterns
        std::map<std::string, std::string> setEnvVars_; // environment variables to be set

        // Members for attaching to a process
        int pid_ = -1;                                  // process ID (int instead of pid_t for portability)

    public:
        Specimen();

        Specimen(int pid);                              // implicit

        Specimen(const boost::filesystem::path&);       // implicit

        Specimen(const boost::filesystem::path &name, const std::vector<std::string> &args);

        Specimen(const std::vector<std::string> &nameAndArgs); // implicit

    public:
        const boost::filesystem::path& program() const;
        void program(const boost::filesystem::path&);
        const std::vector<std::string>& arguments() const;
        void arguments(const std::vector<std::string>&);
        void eraseEnvironmentVariable(const std::string&);

        void eraseMatchingEnvironmentVariables(const boost::regex&);

        void eraseAllEnvironmentVariables();

        void insertEnvironmentVariable(const std::string &name, const std::string &value);

        boost::filesystem::path workingDirectory() const;
        void workingDirectory(const boost::filesystem::path&);
        const BitFlags<Flag>& flags() const;
        BitFlags<Flag>& flags();
        unsigned long persona() const;
        void persona(unsigned long bits);
        bool randomizedAddresses() const;
        void randomizedAddresses(bool);
        int process() const;
        void process(int pid);
        void print(std::ostream &out) const;

        // Used internally.
        char** prepareEnvAdjustments() const;
    };

    using RegisterPage = std::array<uint8_t, 512>;

    struct AllRegisters {
        RegisterPage regs;
        RegisterPage fpregs;
    };

    // Data members
private:
    using UserRegDefs = Sawyer::Container::Map<RegisterDescriptor, size_t>;
    enum class RegPage { NONE, REGS, FPREGS };

    Specimen specimen_;                                 // description of specimen being debugged
    int child_ = 0;                                     // process being debugged (int, not pid_t, for Windows portability)
    DetachMode autoDetach_ = DetachMode::KILL;          // how to detach from the subordinate when deleting this debugger
    int wstat_ = -1;                                    // last status from waitpid
    AddressIntervalSet breakPoints_;                    // list of break point addresses
    int sendSignal_ = 0;                                // pending signal
    UserRegDefs userRegDefs_;                           // how registers map to user_regs_struct in <sys/user.h>
    UserRegDefs userFpRegDefs_;                         // how registers map to user_fpregs_struct in <sys/user.h>
    size_t kernelWordSize_ = 0;                         // cached width in bits of kernel's words
    RegisterPage regsPage_;                             // latest register information read from subordinate
    RegPage regsPageStatus_ = RegPage::NONE;            // what are the contents of regsPage_?
    Sawyer::Optional<rose_addr_t> syscallVa_;           // address of some executable system call instruction.

    // Initialization and destruction.
public:
    static Ptr instance();

    static Ptr instance(const Specimen &specimen, Sawyer::Optional<DetachMode> onDelete = Sawyer::Nothing());

    Linux();
    ~Linux();

    // Attaching and detaching
public:
    void attach(const Specimen&, Sawyer::Optional<DetachMode> onDelete = Sawyer::Nothing());
    Sawyer::Optional<int> processId() const;

    DetachMode detachMode() const;
    void detachMode(DetachMode);
    size_t kernelWordSize();

    int waitpidStatus() const;

    // Running
public:
    void stepIntoSystemCall(ThreadId);

    void runToSystemCall(ThreadId);

    // Register operations
public:
    virtual AllRegisters readAllRegisters(ThreadId);

    virtual void writeAllRegisters(ThreadId, const AllRegisters&);

    // System calls
public:
    int64_t remoteSystemCall(ThreadId, int syscallNumber);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1, uint64_t arg2);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1, uint64_t arg2, uint64_t arg3);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5);
    int64_t remoteSystemCall(ThreadId, int syscallNumber,
                             uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5, uint64_t arg6);
    int64_t remoteSystemCall(ThreadId, int syscallNumber, std::vector<uint64_t> args);
    int remoteOpenFile(ThreadId, const boost::filesystem::path &fileName, unsigned flags, mode_t mode);

    int remoteCloseFile(ThreadId, unsigned remoteFd);

    rose_addr_t remoteMmap(ThreadId, rose_addr_t va, size_t nBytes, unsigned prot, unsigned flags, const boost::filesystem::path&,
                           off_t offset);

    // 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 executionAddress(ThreadId, rose_addr_t) override;
    virtual rose_addr_t executionAddress(ThreadId) override;
    virtual void setBreakPoint(const AddressInterval&) 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 void writeRegister(ThreadId, RegisterDescriptor, const Sawyer::Container::BitVector&) override;
    virtual void writeRegister(ThreadId, RegisterDescriptor, uint64_t value) override;
    virtual size_t readMemory(rose_addr_t va, size_t nBytes, uint8_t *buffer) override;
    virtual std::vector<uint8_t> readMemory(rose_addr_t va, size_t nBytes) override;
    virtual Sawyer::Container::BitVector readMemory(rose_addr_t va, size_t nBytes, ByteOrder::Endianness order) override;
    virtual size_t writeMemory(rose_addr_t va, size_t nBytes, const uint8_t *bytes) override;
    virtual bool isTerminated() override;
    virtual std::string howTerminated() override;

private:
    // Wait for subordinate or throw on error
    void waitForChild();

    // Open /dev/null with the specified flags as the indicated file descriptor, closing what was previously on that
    // descriptor. If an error occurs, the targetFd is closed anyway.
    void devNullTo(int targetFd, int openFlags);

    // Get/set personality in a portable way
    static unsigned long getPersonality();
    static void setPersonality(unsigned long);

    // Address of a system call instruction. The initial search can be expensive, so the result is cached.
    Sawyer::Optional<rose_addr_t> findSystemCall();
};

std::ostream& operator<<(std::ostream&, const Linux::Specimen&);

} // namespace
} // namespace
} // namespace

#endif
#endif