path: root/lib/Debugger/UnixLocalInferiorProcess.cpp

//===-- UnixLocalInferiorProcess.cpp - A Local process on a Unixy system --===//
// 
//                     The LLVM Compiler Infrastructure
//
// This file was developed by the LLVM research group and is distributed under
// the University of Illinois Open Source License. See LICENSE.TXT for details.
// 
//===----------------------------------------------------------------------===//
// 
// This file provides one implementation of the InferiorProcess class, which is
// designed to be used on unixy systems (those that support pipe, fork, exec,
// and signals).
//
// When the process is started, the debugger creates a pair of pipes, forks, and
// makes the child start executing the program.  The child executes the process
// with an IntrinsicLowering instance that turns debugger intrinsics into actual
// callbacks.
//
// This target takes advantage of the fact that the Module* addresses in the
// parent and the Module* addresses in the child will be the same, due to the
// use of fork().  As such, global addresses looked up in the child can be sent
// over the pipe to the debugger.
//
//===----------------------------------------------------------------------===//

#include "llvm/Debugger/InferiorProcess.h"
#include "llvm/Constant.h"
#include "llvm/Instructions.h"
#include "llvm/Module.h"
#include "llvm/ModuleProvider.h"
#include "llvm/Type.h"
#include "llvm/CodeGen/IntrinsicLowering.h"
#include "llvm/ExecutionEngine/GenericValue.h"
#include "llvm/ExecutionEngine/ExecutionEngine.h"
#include "llvm/Support/FileUtilities.h"
#include "llvm/ADT/StringExtras.h"
#include <cerrno>
#include <csignal>
#include <unistd.h>        // Unix-specific debugger support
#include <sys/types.h>
#include <sys/wait.h>
using namespace llvm;

// runChild - Entry point for the child process.
static void runChild(Module *M, const std::vector<std::string> &Arguments,
                     const char * const *envp,
                     FDHandle ReadFD, FDHandle WriteFD);

//===----------------------------------------------------------------------===//
//                        Parent/Child Pipe Protocol
//===----------------------------------------------------------------------===//
//
// The parent/child communication protocol is designed to have the child process
// responding to requests that the debugger makes.  Whenever the child process
// has stopped (due to a break point, single stepping, etc), the child process
// enters a message processing loop, where it reads and responds to commands
// until the parent decides that it wants to continue execution in some way.
//
// Whenever the child process stops, it notifies the debugger by sending a
// character over the wire.
//

namespace {
  /// LocationToken - Objects of this type are sent across the pipe from the
  /// child to the parent to indicate where various stack frames are located.
  struct LocationToken {
    unsigned Line, Col;
    const GlobalVariable *File;
    LocationToken(unsigned L = 0, unsigned C = 0, const GlobalVariable *F = 0)
      : Line(L), Col(C), File(F) {}
  };
}

// Once the debugger process has received the LocationToken, it can make
// requests of the child by sending one of the following enum values followed by
// any data required by that command.  The child responds with data appropriate
// to the command.
//
namespace {
  /// CommandID - This enum defines all of the commands that the child process
  /// can respond to.  The actual expected data and responses are defined as the
  /// enum values are defined.
  ///
  enum CommandID {
    //===------------------------------------------------------------------===//
    // Execution commands - These are sent to the child to from the debugger to
    // get it to do certain things.
    //

    // StepProgram: void->char - This command causes the program to continue
    // execution, but stop as soon as it reaches another stoppoint.
    StepProgram,

    // FinishProgram: FrameDesc*->char - This command causes the program to
    // continue execution until the specified function frame returns.
    FinishProgram, 

    // ContProgram: void->char - This command causes the program to continue
    // execution, stopping at some point in the future.
    ContProgram,

    // GetSubprogramDescriptor: FrameDesc*->GlobalValue* - This command returns
    // the GlobalValue* descriptor object for the specified stack frame.
    GetSubprogramDescriptor,

    // GetParentFrame: FrameDesc*->FrameDesc* - This command returns the frame
    // descriptor for the parent stack frame to the specified one, or null if
    // there is none.
    GetParentFrame,

    // GetFrameLocation - FrameDesc*->LocationToken - This command returns the
    // location that a particular stack frame is stopped at.
    GetFrameLocation,

    // AddBreakpoint - LocationToken->unsigned - This command instructs the
    // target to install a breakpoint at the specified location.
    AddBreakpoint,

    // RemoveBreakpoint - unsigned->void - This command instructs the target to
    // remove a breakpoint.
    RemoveBreakpoint,
  };
}




//===----------------------------------------------------------------------===//
//                            Parent Process Code
//===----------------------------------------------------------------------===//

namespace {
  class IP : public InferiorProcess {
    // ReadFD, WriteFD - The file descriptors to read/write to the inferior
    // process.
    FDHandle ReadFD, WriteFD;

    // ChildPID - The unix PID of the child process we forked.
    mutable pid_t ChildPID;
  public:
    IP(Module *M, const std::vector<std::string> &Arguments,
       const char * const *envp);
    ~IP();

    std::string getStatus() const;

    /// Execution method implementations...
    virtual void stepProgram();
    virtual void finishProgram(void *Frame);
    virtual void contProgram();


    // Stack frame method implementations...
    virtual void *getPreviousFrame(void *Frame) const;
    virtual const GlobalVariable *getSubprogramDesc(void *Frame) const;
    virtual void getFrameLocation(void *Frame, unsigned &LineNo,
                                  unsigned &ColNo,
                                  const GlobalVariable *&SourceDesc) const;

    // Breakpoint implementation methods
    virtual unsigned addBreakpoint(unsigned LineNo, unsigned ColNo,
                                   const GlobalVariable *SourceDesc);
    virtual void removeBreakpoint(unsigned ID);


  private:
    /// startChild - This starts up the child process, and initializes the
    /// ChildPID member.
    ///
    void startChild(Module *M, const std::vector<std::string> &Arguments,
                    const char * const *envp);

    /// killChild - Kill or reap the child process.  This throws the
    /// InferiorProcessDead exception an exit code if the process had already
    /// died, otherwise it just kills it and returns.
    void killChild() const;

  private:
    // Methods for communicating with the child process.  If the child exits or
    // dies while attempting to communicate with it, ChildPID is set to zero and
    // an exception is thrown.

    /// readFromChild - Low-level primitive to read some data from the child,
    /// throwing an exception if it dies.
    void readFromChild(void *Buffer, unsigned Size) const;

    /// writeToChild - Low-level primitive to send some data to the child
    /// process, throwing an exception if the child died.
    void writeToChild(void *Buffer, unsigned Size) const;

    /// sendCommand - Send a command token and the request data to the child.
    ///
    void sendCommand(CommandID Command, void *Data, unsigned Size)<