//===-- DynamicLoader.h -----------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_DynamicLoader_h_
#define liblldb_DynamicLoader_h_

// Project includes
#include "lldb/lldb-private.h"
#include "lldb/Core/Error.h"
#include "lldb/Core/PluginInterface.h"

namespace lldb_private {

//----------------------------------------------------------------------
/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
/// @brief A plug-in interface definition class for dynamic loaders.
///
/// Dynamic loader plug-ins track image (shared library) loading and
/// unloading. The class is initialized given a live process that is
/// halted at its entry point or just after attaching.
///
/// Dynamic loader plug-ins can track the process by registering
/// callbacks using the:
/// Process::RegisterNotificationCallbacks (const Notifications&)
/// function.
///
/// Breakpoints can also be set in the process which can register
/// functions that get called using:
/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
/// These breakpoint callbacks return a boolean value that indicates if
/// the process should continue or halt and should return the global
/// setting for this using:
/// DynamicLoader::StopWhenImagesChange() const.
//----------------------------------------------------------------------
class DynamicLoader :
    public PluginInterface
{
public:
    //------------------------------------------------------------------
    /// Find a dynamic loader plugin for a given process.
    ///
    /// Scans the installed DynamicLoader plug-ins and tries to find
    /// an instance that can be used to track image changes in \a
    /// process.
    ///
    /// @param[in] process
    ///     The process for which to try and locate a dynamic loader
    ///     plug-in instance.
    ///
    /// @param[in] plugin_name
    ///     An optional name of a specific dynamic loader plug-in that
    ///     should be used. If NULL, pick the best plug-in.
    //------------------------------------------------------------------
    static DynamicLoader*
    FindPlugin (Process *process, const char *plugin_name);

    //------------------------------------------------------------------
    /// Construct with a process.
    //------------------------------------------------------------------
    DynamicLoader (Process *process);

    //------------------------------------------------------------------
    /// Destructor.
    ///
    /// The destructor is virtual since this class is designed to be
    /// inherited from by the plug-in instance.
    //------------------------------------------------------------------
    ~DynamicLoader() override;

    //------------------------------------------------------------------
    /// Called after attaching a process.
    ///
    /// Allow DynamicLoader plug-ins to execute some code after
    /// attaching to a process.
    //------------------------------------------------------------------
    virtual void
    DidAttach () = 0;

    //------------------------------------------------------------------
    /// Called after launching a process.
    ///
    /// Allow DynamicLoader plug-ins to execute some code after
    /// the process has stopped for the first time on launch.
    //------------------------------------------------------------------
    virtual void
    DidLaunch () = 0;
    
    
    //------------------------------------------------------------------
    /// Helper function that can be used to detect when a process has
    /// called exec and is now a new and different process. This can
    /// be called when necessary to try and detect the exec. The process
    /// might be able to answer this question, but sometimes it might
    /// not be able and the dynamic loader often knows what the program
    /// entry point is. So the process and the dynamic loader can work
    /// together to detect this.
    //------------------------------------------------------------------
    virtual bool
    ProcessDidExec ()
    {
        return false;
    }
    //------------------------------------------------------------------
    /// Get whether the process should stop when images change.
    ///
    /// When images (executables and shared libraries) get loaded or
    /// unloaded, often debug sessions will want to try and resolve or
    /// unresolve breakpoints that are set in these images. Any
    /// breakpoints set by DynamicLoader plug-in instances should
    /// return this value to ensure consistent debug session behaviour.
    ///
    /// @return
    ///     Returns \b true if the process should stop when images
    ///     change, \b false if the process should resume.
    //------------------------------------------------------------------
    bool
    GetStopWhenImagesChange () const;

    //------------------------------------------------------------------
    /// Set whether the process should stop when images change.
    ///
    /// When images (executables and shared libraries) get loaded or
    /// unloaded, often debug sessions will want to try and resolve or
    /// unresolve breakpoints that are set in these images. The default
    /// is set so that the process stops when images change, but this
    /// can be overridden using this function callback.
    ///
    /// @param[in] stop
    ///     Boolean value that indicates whether the process should stop
    ///     when images change.
    //------------------------------------------------------------------
    void
    SetStopWhenImagesChange (bool stop);

    //------------------------------------------------------------------
    /// Provides a plan to step through the dynamic loader trampoline
    /// for the current state of \a thread.
    ///
    ///
    /// @param[in] stop_others
    ///     Whether the plan should be set to stop other threads.
    ///
    /// @return
    ///    A pointer to the plan (caller owned) or NULL if we are not at such
    ///    a trampoline.
    //------------------------------------------------------------------
    virtual lldb::ThreadPlanSP
    GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;


    //------------------------------------------------------------------
    /// Some dynamic loaders provide features where there are a group of symbols "equivalent to"
    /// a given symbol one of which will be chosen when the symbol is bound.  If you want to
    /// set a breakpoint on one of these symbols, you really need to set it on all the
    /// equivalent symbols.
    ///
    ///
    /// @param[in] original_symbol
    ///     The symbol for which we are finding equivalences.
    ///
    /// @param[in] module_list
    ///     The set of modules in which to search.
    ///
    /// @param[out] equivalent_symbols
    ///     The equivalent symbol list - any equivalent symbols found are appended to this list.
    ///
    /// @return
    ///    Number of equivalent symbols found.
    //------------------------------------------------------------------
    virtual size_t
    FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
    {
        return 0;
    }

    //------------------------------------------------------------------
    /// Ask if it is ok to try and load or unload an shared library 
    /// (image).
    ///
    /// The dynamic loader often knows when it would be ok to try and
    /// load or unload a shared library. This function call allows the
    /// dynamic loader plug-ins to check any current dyld state to make
    /// sure it is an ok time to load a shared library.
    ///
    /// @return
    ///     \b true if it is currently ok to try and load a shared 
    ///     library into the process, \b false otherwise.
    //------------------------------------------------------------------
    virtual Error
    CanLoadImage () = 0;

    //------------------------------------------------------------------
    /// Ask if the eh_frame information for the given SymbolContext should
    /// be relied on even when it's the first frame in a stack unwind.
    /// 
    /// The CFI instructions from the eh_frame section are normally only
    /// valid at call sites -- places where a program could throw an 
    /// exception and need to unwind out.  But some Modules may be known 
    /// to the system as having reliable eh_frame information at all call 
    /// sites.  This would be the case if the Module's contents are largely
    /// hand-written assembly with hand-written eh_frame information.
    /// Normally when unwinding from a function at the beginning of a stack
    /// unwind lldb will examine the assembly instructions to understand
    /// how the stack frame is set up and where saved registers are stored.
    /// But with hand-written assembly this is not reliable enough -- we need
    /// to consult those function's hand-written eh_frame information.
    ///
    /// @return
    ///     \b True if the symbol context should use eh_frame instructions
    ///     unconditionally when unwinding from this frame.  Else \b false,
    ///     the normal lldb unwind behavior of only using eh_frame when the
    ///     function appears in the middle of the stack.
    //------------------------------------------------------------------
    virtual bool
    AlwaysRelyOnEHUnwindInfo (SymbolContext &sym_ctx)
    {
       return false;
    }

    //------------------------------------------------------------------
    /// Retrieves the per-module TLS block for a given thread.
    ///
    /// @param[in] module
    ///     The module to query TLS data for.
    ///
    /// @param[in] thread
    ///     The specific thread to query TLS data for.
    ///
    /// @return
    ///     If the given thread has TLS data allocated for the
    ///     module, the address of the TLS block. Otherwise
    ///     LLDB_INVALID_ADDRESS is returned.
    //------------------------------------------------------------------
    virtual lldb::addr_t
    GetThreadLocalData (const lldb::ModuleSP module, const lldb::ThreadSP thread)
    {
        return LLDB_INVALID_ADDRESS;
    }

    /// Locates or creates a module given by @p file and updates/loads the
    /// resulting module at the virtual base address @p base_addr.
    virtual lldb::ModuleSP
    LoadModuleAtAddress(const lldb_private::FileSpec &file,
                        lldb::addr_t link_map_addr,
                        lldb::addr_t base_addr,
                        bool base_addr_is_offset);

protected:
    //------------------------------------------------------------------
    // Utility methods for derived classes
    //------------------------------------------------------------------

    /// Checks to see if the target module has changed, updates the target
    /// accordingly and returns the target executable module.
    lldb::ModuleSP
    GetTargetExecutable();

    /// Updates the load address of every allocatable section in @p module.
    ///
    /// @param module The module to traverse.
    ///
    /// @param link_map_addr The virtual address of the link map for the @p module.
    ///
    /// @param base_addr The virtual base address @p module is loaded at.
    virtual void
    UpdateLoadedSections(lldb::ModuleSP module,
                         lldb::addr_t link_map_addr,
                         lldb::addr_t base_addr,
                         bool base_addr_is_offset);

    // Utility method so base classes can share implementation of UpdateLoadedSections
    void
    UpdateLoadedSectionsCommon(lldb::ModuleSP module,
                               lldb::addr_t base_addr,
                               bool base_addr_is_offset);

    /// Removes the loaded sections from the target in @p module.
    ///
    /// @param module The module to traverse.
    virtual void
    UnloadSections(const lldb::ModuleSP module);

    // Utility method so base classes can share implementation of UnloadSections
    void
    UnloadSectionsCommon(const lldb::ModuleSP module);

    const lldb_private::SectionList *
    GetSectionListFromModule(const lldb::ModuleSP module) const;

    // Read an unsigned int of the given size from memory at the given addr.
    // Return -1 if the read fails, otherwise return the result as an int64_t.
    int64_t
    ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);

    // Read a pointer from memory at the given addr.
    // Return LLDB_INVALID_ADDRESS if the read fails.
    lldb::addr_t
    ReadPointer(lldb::addr_t addr);

    //------------------------------------------------------------------
    // Member variables.
    //------------------------------------------------------------------
    Process* m_process; ///< The process that this dynamic loader plug-in is tracking.

private:

    DISALLOW_COPY_AND_ASSIGN (DynamicLoader);
};

} // namespace lldb_private

#endif // liblldb_DynamicLoader_h_
