src/camera/drivers/controller/processing_node.h

// 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_CAMERA_DRIVERS_CONTROLLER_PROCESSING_NODE_H_
#define SRC_CAMERA_DRIVERS_CONTROLLER_PROCESSING_NODE_H_

#include <fuchsia/camera2/cpp/fidl.h>
#include <fuchsia/hardware/gdc/cpp/banjo.h>
#include <fuchsia/hardware/isp/cpp/banjo.h>
#include <lib/async/cpp/task.h>
#include <lib/fit/thread_checker.h>
#include <lib/stdcompat/source_location.h>
#include <zircon/assert.h>

#include <mutex>
#include <queue>
#include <vector>

#include <fbl/macros.h>

#include "src/camera/drivers/controller/configs/internal_config.h"
#include "src/camera/drivers/controller/memory_allocation.h"
#include "src/camera/lib/tokens/tokens.h"

namespace camera {

// A ProcessNode is an abstract base class that represents a logical or physical functional unit
// within the camera hardware pipeline. A node owns its output collection but not its input
// collection. Derived classes override the various methods based on their need.
class ProcessNode {
 public:
  // Wrapper for a set of input/output buffer collections and their associated formats.
  struct BufferAttachments {
    std::optional<std::reference_wrapper<BufferCollection>> input_collection;
    std::optional<std::reference_wrapper<const std::vector<fuchsia::images2::ImageFormat>>>
        input_formats;
    std::optional<std::reference_wrapper<BufferCollection>> output_collection;
    std::optional<std::reference_wrapper<const std::vector<fuchsia::images2::ImageFormat>>>
        output_formats;
  };

  using FrameToken = SharedToken<const uint32_t>;

  // FrameCallback is a caller-provided handler that nodes should invoke when they have produced a
  // new frame.
  using FrameCallback = fit::function<void(FrameToken, frame_metadata_t)>;
  ProcessNode(async_dispatcher_t* dispatcher, NodeType type, BufferAttachments attachments,
              FrameCallback frame_callback);

  // Destroys the node instance. The caller must call Shutdown before destroying the instance or
  // the process will terminate. If the node implementation relies on singleton hardware resources
  // that cannot be safely accessed concurrently by multiple instances of the class, then the node
  // must ensure that all such resources are released prior returning from this destructor.
  virtual ~ProcessNode();

  // Returns the NodeType specified on creation of the object.
  NodeType Type() const;

  // Informs the node that it should begin processing the frame specified by the given token and
  // associated with the given metadata. The node must maintain the token until it is no longer
  // needed, after which point it can safely be destroyed.
  virtual void ProcessFrame(FrameToken token, frame_metadata_t metadata) = 0;

  // Requests that the node node begin producing frames using the specified format index. As the
  // node may pipeline frames, it is acceptable to continue producing frames at the previous
  // format. But the node must invoke the provided callback after the last frame at the previous
  // format was sent and before the first frame of the new format is sent.
  //
  // The caller may request multiple format changes without receiving frames. In these cases,
  // the node must invoke all callbacks in the order received, but it does not need to produce a
  // frame with each format requested. For example, if the caller requests a change from A to B to
  // C, it is okay to produce a frame with format A, then invoke callback B followed by C, and then
  // produce a frame with format C.
  virtual void SetOutputFormat(uint32_t output_format_index, fit::closure callback) = 0;

  // Requests that the node cease processing frames and begin shutting itself down. The node must
  // perform any flushing required in order to safely return frames that it received via
  // ProcessFrame calls. The node must ensure all pending ProcessFrame callbacks are appropriately
  // invoked, and then invoke the callback specified in this method, after which the node must make
  // no further calls to the frame_callback provided during creation. After requesting shutdown, the
  // caller will ensure that no further calls are made to the node.
  void Shutdown(fit::closure callback);

  // Assigns a label to the node for logging purposes.
  void SetLabel(std::string label);

 protected:
  // Nodes should use this method to invoke the top-level FrameCallback this node was created with.
  void SendFrame(uint32_t index, frame_metadata_t metadata, fit::closure release_callback) const;

  // Provides the node access to the input buffer collection it was created with.
  const fuchsia::sysmem2::BufferCollectionInfo& InputBuffers() const;

  // Provides the node access to the image formats associated with its inputs.
  const std::vector<fuchsia::images2::ImageFormat>& InputFormats() const;

  // Provides the node access to the output buffer collection it was created with.
  const fuchsia::sysmem2::BufferCollectionInfo& OutputBuffers() const;

  // Provides the node access to the image formats associated with its outputs.
  const std::vector<fuchsia::images2::ImageFormat>& OutputFormats() const;

  // fuchsia.hardware.camerahwaccel.*Callback implementations. The node receives these callbacks
  // serially on the dispatcher it was created with.
  virtual void HwFrameReady(frame_available_info_t info) = 0;
  virtual void HwFrameResolutionChanged(frame_available_info_t info) = 0;
  virtual void HwTaskRemoved(task_remove_status_t status) = 0;

  // Nodes must implement this method. It is distinct from the non-virtual Shutdown method in order
  // to allow the base class visibility into the state of the node's shutdown. Refer to the
  // description of that method for details.
  virtual void ShutdownImpl(fit::closure callback) = 0;

  // Returns c-style callback pointers. When invoked by a consumer, the corresponding Hw* callback
  // is invoked via the node's dispatcher. The callsite location is used to annotate the callback
  // logs and trace events.
  const hw_accel_frame_callback* GetHwFrameReadyCallback(
      cpp20::source_location location = cpp20::source_location::current());
  const hw_accel_res_change_callback* GetHwFrameResolutionChangeCallback(
      cpp20::source_location location = cpp20::source_location::current());
  const hw_accel_remove_task_callback* GetHwTaskRemovedCallback(
      cpp20::source_location location = cpp20::source_location::current());

  // Convenience method that wraps a call to async::PostTask with trace markers. These produce flow
  // graph indicators which allow tracing the origin of a callback. By default, the trace events are
  // annotated with the callsite of this method.
  void PostTask(fit::closure task,
                cpp20::source_location location = cpp20::source_location::current());

  // Provide subclasses with the ability to use label_ in log messages.
  std::string GetLabel() { return label_; }

 private:
  // Static methods bound to the c-style callbacks.
  static void StaticHwFrameReady(void* ctx, const frame_available_info_t* info);
  static void StaticHwFrameResolutionChanged(void* ctx, const frame_available_info_t* info);
  static void StaticHwTaskRemoved(void* ctx, task_remove_status_t status);

  // Dispatcher for the frame processing loop.
  async_dispatcher_t* dispatcher_;
  // Indicates the specific sub-type of process node.
  const NodeType type_;
  // Buffer collections and formats attached to the node.
  BufferAttachments attachments_;
  // Caller-provided callback to be invoked by the node when a new frame is available.
  FrameCallback frame_callback_;
  // Containers for the c-style callbacks. These are associated with the OnHw* callbacks.
  struct {
    const hw_accel_frame_callback frame;
    std::vector<cpp20::source_location> frame_callsites;
    const hw_accel_res_change_callback res_change;
    std::vector<cpp20::source_location> res_change_callsites;
    const hw_accel_remove_task_callback remove_task;
    std::vector<cpp20::source_location> remove_task_callsites;
  } hwaccel_callbacks_;
  // Shutdown state tracking for caller validation.
  struct {
    bool requested = false;
    bool completed = false;
  } shutdown_state_;
  std::string label_ = "<unset>";
};

}  // namespace camera

#endif  // SRC_CAMERA_DRIVERS_CONTROLLER_PROCESSING_NODE_H_