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 <Rose/BinaryAnalysis/AddressIntervalSet.h>
#include <Rose/BinaryAnalysis/SystemCall.h>
 
#include <Sawyer/Optional.h>
#include <sys/ptrace.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
        Architecture::BaseConstPtr arch_;               // optional architecture
 
        // 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);
        Architecture::BaseConstPtr architecture() const;
        void architecture(const Architecture::BaseConstPtr&);
        bool randomizedAddresses() const;
        void randomizedAddresses(bool);
        int process() const;
        void process(int pid);
        void print(std::ostream &out) const;
 
        // Used internally.
        char** prepareEnvAdjustments() const;
    };
 
    // Private types
private:
    using UserRegDefs = Sawyer::Container::Map<RegisterDescriptor, size_t>;
 
    // What type of register values are cached?
    enum class RegCacheType { NONE, REGS, FPREGS };
 
    // Low-level collection of register values.
    using RegPage = std::array<uint8_t, 512>;
 
    // Low-level structure containing values for all registers.
    struct AllRegValues {
        RegPage regs;                                   // integer registers
        RegPage fpregs;                                 // floating-point registers
    };
 
 
    // Data members
private:
    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
    RegPage regCache_;                                  // latest register information read from subordinate
    RegCacheType regCacheType_ = RegCacheType::NONE;    // what are the contents of regsPage_?
    Sawyer::Optional<Address> syscallVa_;               // address of some executable system call instruction.
    SystemCall syscallDecls_;                           // to get declarations for system calls
 
    // 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);
 
    int pendingSignal() const;
 
    // 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);
 
    Address remoteMmap(ThreadId, Address 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, Address) override;
    virtual Address executionAddress(ThreadId) 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 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 std::vector<RegisterDescriptor> availableRegisters() override;
    virtual Sawyer::Container::BitVector readAllRegisters(ThreadId) override;
    virtual void writeAllRegisters(ThreadId, const Sawyer::Container::BitVector&) override;
 
private:
    // Initialize after construction
    void init();
 
    // 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<Address> findSystemCall();
 
    // Low-level methods to read and write data for all known registers.
    AllRegValues loadAllRegisters(ThreadId);
    void saveAllRegisters(ThreadId, const AllRegValues&);
 
    // Update the register cache to contain the specified register. Return the offset to the start of the register
    // inside the register cache.
    size_t updateRegCache(RegisterDescriptor);
 
    // Send a ptrace command
    long sendCommand(__ptrace_request, void *addr = nullptr, void *data = nullptr);
    long sendCommandInt(__ptrace_request, void *addr, int i);
 
    // Load system call declarations from the appropriate header file
    void declareSystemCalls();
 
    // Return the known specimen architecture from the `specimenArchitecture` property, or guess something. Returns null if a guess
    // isn't even possible.
    Architecture::BaseConstPtr guessSpecimenArchitecture() const;
};
 
std::ostream& operator<<(std::ostream&, const Linux::Specimen&);
 
} // namespace
} // namespace
} // namespace
 
#endif
#endif