// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_STACK_H_
#define SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_STACK_H_

#include <optional>
#include <vector>

#include "lib/fit/function.h"
#include "src/developer/debug/ipc/protocol.h"
#include "src/developer/debug/zxdb/symbols/location.h"
#include "src/lib/fxl/macros.h"
#include "src/lib/fxl/memory/weak_ptr.h"

namespace zxdb {

class Err;
class Frame;
class FrameFingerprint;

// Represents the stack of a thread that's suspended or blocked in an exception. If a thread is
// running, blocked (not in an exception), or in any other state, the stack frames are not
// available.
//
// EMPTY, PARTIAL AND COMPLETE STACKS
// ----------------------------------
// When a thread is suspended or blocked in an exception, it will UNUSUALLY have its top frame
// available (the current IP and stack position) and the next (the calling frame) if possible.
//
// Sometimes a thread might have an empty stack (and hence no current location) from an exception.
// This is because exceptions are delivered from the kernel asynchronously, and by the time an
// exception is handled in the debug agent, the thread may have been killed. This will result in
// failred register reads for the thread and no stack or location. Code should never assume there
// are any stack frames.
//
// If the full backtrace is needed, SyncFrames() can be called which will compute the full backtrace
// and issue the callback when complete. This backtrace will be cached until the thread is resumed.
//
// INLINE FRAMES
// -------------
// The thread's current position can be in multiple inline frames at the same time (the first
// address of an inline function is both the first instruction of that function, and the virtual
// "call" of that function in the outer frame). This only applies to the topmost set of inline
// frames since anything below the first physical frame is unambiguous).
//
// To make stepping work as expected, code can adjust which of these ambiguous inline frames the
// stack reports is the top, and inline frames above that are hidden from the normal size() and
// operator[] functions.
class Stack {
 public:
  struct SyncFrameOptions {
    // Clears the current set of frames before unwinding from the current location, forcing a
    // complete stack unwind.
    bool force_update = false;
    // Requests the unwinder to be called from the target instead of locally. This can be useful
    // when debug info from either an unstripped or split binary is insufficient to completely
    // unwind (which is difficult to detect automatically).
    bool remote_unwind = false;
  };

  // Provides a way for this class to talk to the environment.
  class Delegate {
   public:
    // Requests that the Stack be provided with a new set of frames. The implementation should
    // asynchronously request the frame information, call Stack::SetFrames(), then issue the
    // callback to indicate completion.
    //
    // The callback should be issued with an error if the object is destroyed during processing.
    virtual void SyncFramesForStack(const SyncFrameOptions& opts,
                                    fit::callback<void(const Err&)> callback) = 0;

    // Constructs a Frame implementation for the given IPC stack frame and location. The location
    // must be an input since inline frame expansion requires stack frames be constructed with
    // different symbols than just looking up the address in the symbols.
    virtual std::unique_ptr<Frame> MakeFrameForStack(const debug_ipc::StackFrame& input,
                                                     Location location) = 0;

    virtual Location GetSymbolizedLocationForAddress(uint64_t address) = 0;

    // Notification that the frames have been changed.
    virtual void DidUpdateStackFrames() = 0;
  };

  // The delegate must outlive this class.
  explicit Stack(Delegate* delegate);

  ~Stack();

  fxl::WeakPtr<Stack> GetWeakPtr();

  // Returns whether the frames in this backtrace are all the frames or only the top 1-2 (see
  // class-level comment above).
  bool has_all_frames() const { return has_all_frames_; }

  size_t size() const { return frames_.size() - hide_ambiguous_inline_frame_count_; }
  bool empty() const { return frames_.empty(); }

  // Access into the individual frames. The topmost stack frame is index 0. There may be hidden
  // inline frames above index 0. Callers should always check the stack size() before accessing
  // since the stack is never guaranteed to have elements in it (even during processing an
  // exception -- see class comment above).
  Frame* operator[](size_t index) {
    return frames_[index + hide_ambiguous_inline_frame_count_].get();
  }
  const Frame* operator[](size_t index) const {
    return frames_[index + hide_ambiguous_inline_frame_count_].get();
  }

  // Returns the index of the frame pointer in this stack if it is there.
  std::optional<size_t> IndexForFrame(const Frame* frame) const;

  // Returns the inline depth of the frame at the given index. If the frame is a physical frame,
  // this will be 0.
  size_t InlineDepthForIndex(size_t index) const;

  // Computes the stack frame fingerprint for the stack frame at the given index. The index must be
  // valid in the current set of frames in this stack object.
  //
  // See frame_fingerprint.h for a discussion on fingerprints.
  FrameFingerprint GetFrameFingerprint(size_t frame_index) const;

  // Sets the number of inline frames at the top of the stack to show. See the class-level comment
  // above for more.
  //
  // Anything trimmed should have its current position at the beginning of a code range of an inline
  // function for this trimming to make logical sense. The number of inline frames at the top of the
  // stack can be modified.
  //
  // The "top inline frame count" is the number of inline frames above the topmost physical frame
  // that exist in the stack. This does not change when the hide count is modified.
  //
  // From 0 to "top inline frame count" of inline frames can be hidden or unhidden. By default they
  // are all visible (hide count = 0).
  size_t GetAmbiguousInlineFrameCount() const;
  size_t hide_ambiguous_inline_frame_count() const { return hide_ambiguous_inline_frame_count_; }
  void SetHideAmbiguousInlineFrameCount(size_t hide_count);

  // Queries the size and for frames at indices ignoring any hidden inline frames. With
  // FrameAtIndexIndcludingHiddenInline(), the 0th index is always the innermost inline frame and is
  // not affected by SetTopInlineFrameShowCount().
  size_t SizeIncludingHiddenInline() const { return frames_.size(); }
  Frame* FrameAtIndexIncludingHiddenInline(size_t index) { return frames_[index].get(); }

  // Requests that all frame information be updated. This can be used to (asynchronously) populate
  // the frames when a Stack has only partial frame information, and it can be used to force an
  // update from the remote system in case anything changed.
  //
  // Normally frame info is cached. Setting "force" will unconditionally clear all state. This will
  // invalidate any weak pointers into the stack and could change the frame indices in the
  // frontend.
  //
  // If the stack is destroyed before the frames can be synced, the callback will be issued with an
  // error.
  void SyncFrames(const SyncFrameOptions& opts, fit::callback<void(const Err&)> callback);

  // Provides a new set of frames computed by a backtrace in the debug_agent. In normal operation
  // this is called by the Thread.
  //
  // This can be called in two cases: (1) when a thread stops to provide a new stack, and (2) when
  // updating a stack with more frames. If there are existing frames when SetFrames is called, it
  // will assume state (2) if possible (the stack could have changed out from under us) and will
  // attempt to preserve the ambiguous inline hide count, etc. consistent with updating an existing
  // stack.
  //
  // If you don't want this behavior, call ClearFrames() first. ClearFrames() will be called whever
  // a thread is resumed so fresh stops should get this behavior by default.
  void SetFrames(debug_ipc::ThreadRecord::StackAmount amount,
                 const std::vector<debug_ipc::StackFrame>& frames);

  // Sets the frames to a known set to provide synthetic stacks for tests.
  void SetFramesForTest(std::vector<std::unique_ptr<Frame>> frames, bool has_all);

  // Removes all frames. In normal operation this is called by the Thread when things happen that
  // invalidate all frames such as resuming the thread.
  //
  // This should generally only be called by the Thread. Otherwise the thread state (whether it's
  // stopped, etc.) can diverge from the stack state (threads in certain stopped states are always
  // expected to have at least one stack frame).
  void ClearFrames();

 private:
  // Symbolizes the given frame address, taking into account that non-topmost frames should slow the
  // call location (previous instruction) rather than the return address.
  Location SymbolizeFrameAddress(uint64_t address,
                                 debug_ipc::StackFrame::AddressType pc_is_return_address) const;

  // Adds the given stack frame to the end of the current stack (going backwards in time). Inline
  // frames will be expanded so this may append more than one frame.
  void AppendFrame(const debug_ipc::StackFrame& record);

  Delegate* delegate_;

  std::vector<std::unique_ptr<Frame>> frames_;
  bool has_all_frames_ = false;

  // Set when a "forced" frame update is requested. This will clear any previous state when new
  // frames are available.
  bool force_update_in_progress_ = false;

  // Number of frames to hide from size() and operator[] that are inline frames at the top of the
  // stack that shouldn't be exposed right now.
  size_t hide_ambiguous_inline_frame_count_ = 0;

  fxl::WeakPtrFactory<Stack> weak_factory_;

  FXL_DISALLOW_COPY_AND_ASSIGN(Stack);
};

}  // namespace zxdb

#endif  // SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_STACK_H_