src/storage/blobfs/page_loader.h - fuchsia - Git at Google

 // 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_STORAGE_BLOBFS_PAGE_LOADER_H_
 #define SRC_STORAGE_BLOBFS_PAGE_LOADER_H_

 #ifndef __Fuchsia__
 #error Fuchsia-only Header
 #endif

 #include <lib/async-loop/cpp/loop.h>
 #include <lib/async-loop/default.h>
 #include <lib/async/dispatcher.h>
 #include <lib/fzl/vmo-mapper.h>
 #include <lib/zx/pager.h>

 #include <functional>
 #include <memory>

 #include "src/storage/blobfs/blobfs_metrics.h"
 #include "src/storage/blobfs/compression/external_decompressor.h"
 #include "src/storage/blobfs/loader_info.h"
 #include "src/storage/blobfs/transaction_manager.h"
 #include "src/storage/blobfs/transfer_buffer.h"
 #include "src/storage/lib/vfs/cpp/paged_vfs.h"
 #include "src/storage/lib/watchdog/include/lib/watchdog/watchdog.h"

 namespace blobfs {

 // Wrapper enum for error codes supported by the zx_pager_op_range(ZX_PAGER_OP_FAIL) syscall, used
 // to communicate userpager errors to the kernel, so that the error can be propagated to the
 // originator of the page request (if required), and the waiting thread can be unblocked. We use
 // this wrapper enum instead of a raw zx_status_t as not all error codes are supported.
 enum class PagerErrorStatus : zx_status_t {
   kErrIO = ZX_ERR_IO,
   kErrDataIntegrity = ZX_ERR_IO_DATA_INTEGRITY,
   kErrBadState = ZX_ERR_BAD_STATE,
   // This value is not supported by zx_pager_op_range(). Instead, it is used to determine if the
   // zx_pager_op_range() call is required in the first place - PagerErrorStatus::kOK indicates no
   // error, so we don't make the call.
   kOK = ZX_OK,
 };

 constexpr PagerErrorStatus ToPagerErrorStatus(zx_status_t status) {
   switch (status) {
     case ZX_OK:
       return PagerErrorStatus::kOK;
     // ZX_ERR_IO_DATA_INTEGRITY is the only error code in the I/O class of errors that we
     // distinguish. For everything else return ZX_ERR_IO.
     case ZX_ERR_IO_DATA_INTEGRITY:
       return PagerErrorStatus::kErrDataIntegrity;
     case ZX_ERR_IO:
     case ZX_ERR_IO_DATA_LOSS:
     case ZX_ERR_IO_INVALID:
     case ZX_ERR_IO_MISSED_DEADLINE:
     case ZX_ERR_IO_NOT_PRESENT:
     case ZX_ERR_IO_OVERRUN:
     case ZX_ERR_IO_REFUSED:
     case ZX_ERR_PEER_CLOSED:
       return PagerErrorStatus::kErrIO;
     // Return ZX_ERR_BAD_STATE by default.
     default:
       return PagerErrorStatus::kErrBadState;
   }
 }

 // Applies the scheduling deadline profile to the given pager thread.
 void SetDeadlineProfile(const std::vector<zx::unowned_thread>& threads);

 // Encapsulates a user pager, its associated thread and transfer buffer.
 class PageLoader {
  public:
   DISALLOW_COPY_ASSIGN_AND_MOVE(PageLoader);

   // Resources needed for each worker thread.
   struct WorkerResources {
     WorkerResources(std::unique_ptr<TransferBuffer> uncompressed,
                     std::unique_ptr<TransferBuffer> compressed)
         : uncompressed_buffer(std::move(uncompressed)), compressed_buffer(std::move(compressed)) {}

     std::unique_ptr<TransferBuffer> uncompressed_buffer;
     std::unique_ptr<TransferBuffer> compressed_buffer;
   };

   // Abstracts out how pages are supplied to the system.
   using PageSupplier = std::function<zx::result<>(uint64_t offset, uint64_t length,
                                                   const zx::vmo& aux_vmo, uint64_t aux_offset)>;

   // Creates an instance of PageLoader.
   // A new thread is created and started to process page fault requests.
   // |uncompressed_buffer| is used to retrieve and buffer uncompressed data from the underlying
   // storage. |resources| is a set of resources needed for each individual |Worker| so only as many
   // pager threads are supported as there are sets of resources. |decompression_buffer_size| is the
   // size of the scratch buffer to use for decompression.
   [[nodiscard]] static zx::result<std::unique_ptr<PageLoader>> Create(
       std::vector<std::unique_ptr<WorkerResources>> resources, size_t decompression_buffer_size,
       BlobfsMetrics* metrics, DecompressorCreatorConnector* decompression_connector);

   // Invoked on a read request. Reads in the requested byte range [|offset|, |offset| + |length|)
   // for the inode associated with |info->identifier| into the |transfer_buffer_|, and then moves
   // those pages to the destination |vmo|. If |verifier_info| is not null, uses it to verify the
   // pages prior to transferring them to the destination vmo.
   //
   // How the pages are supplied to the caller is defined by the PageSupplier callback parameter.
   //
   // If an error is encountered, the error code is returned as a |PagerErrorStatus|. This error code
   // is communicated to the kernel with the zx_pager_op_range(ZX_PAGER_OP_FAIL) syscall.
   // |PagerErrorStatus| wraps the supported error codes for ZX_PAGER_OP_FAIL.
   // 1. ZX_ERR_IO - Failure while reading the required data from the block device.
   // 2. ZX_ERR_IO_DATA_INTEGRITY - Failure while verifying the contents read in.
   // 3. ZX_ERR_BAD_STATE - Any other type of failure which prevents us from successfully completing
   // the page request, e.g. failure while decompressing, or while transferring pages from the
   // transfer buffer etc.
   [[nodiscard]] PagerErrorStatus TransferPages(const PageSupplier& page_supplier, uint64_t offset,
                                                uint64_t length, const LoaderInfo& info);

  private:
   class Worker {
    public:
     DISALLOW_COPY_ASSIGN_AND_MOVE(Worker);
     // Creates a Worker resource. This resource is not thread-safe and should be associated with a
     // single thread, or protected via mutex, while serving page faults.
     // |uncompressed_buffer| is used to retrieve and buffer uncompressed data from the underlying
     // storage. |compressed_buffer| is used to retrieve and buffer compressed data from the
     // underlying storage. |decompression_buffer_size| is the size of the scratch buffer to use for
     // decompression.
     [[nodiscard]] static zx::result<std::unique_ptr<Worker>> Create(
         std::unique_ptr<WorkerResources> resources, size_t decompression_buffer_size,
         BlobfsMetrics* metrics, DecompressorCreatorConnector* decompression_connector);

     // See |PageLoader::TransferPages()| which simply selects which Worker to delegate the
     // actual work to.
     [[nodiscard]] PagerErrorStatus TransferPages(const PageLoader::PageSupplier& page_supplier,
                                                  uint64_t offset, uint64_t length,
                                                  const LoaderInfo& info);

    private:
     Worker(size_t decompression_buffer_size, BlobfsMetrics* metrics);

     PagerErrorStatus TransferChunkedPages(const PageLoader::PageSupplier& page_supplier,
                                           uint64_t offset, uint64_t length, const LoaderInfo& info);
     PagerErrorStatus TransferUncompressedPages(const PageLoader::PageSupplier& page_supplier,
                                                uint64_t offset, uint64_t length,
                                                const LoaderInfo& info);

     // Scratch buffer for pager transfers of uncompressed data.
     // NOTE: Per the constraints imposed by |zx_pager_supply_pages|, the VMO owned by this buffer
     // needs to be unmapped before calling |zx_pager_supply_pages|. Map
     // |uncompressed_transfer_buffer_.vmo()| only when an explicit address is required, e.g. for
     // verification, and unmap it immediately after.
     std::unique_ptr<TransferBuffer> uncompressed_transfer_buffer_;

     // Scratch buffer for pager transfers of compressed data.
     // Unlike the above transfer buffer, this never needs to be unmapped since we will be calling
     // |zx_pager_supply_pages| on the |decompression_buffer_|.
     std::unique_ptr<TransferBuffer> compressed_transfer_buffer_;

     // A persistent mapping for |compressed_transfer_buffer_|.
     fzl::VmoMapper compressed_mapper_;

     // This is the buffer that can be written to by the other end of the
     // |decompressor_client_| connection. The contents are not to be trusted and
     // may be changed at any time, so they need to be copied out prior to
     // verification.
     zx::vmo sandbox_buffer_;

     // Scratch buffer for decompression.
     // NOTE: Per the constraints imposed by |zx_pager_supply_pages|, this needs to be unmapped
     // before calling |zx_pager_supply_pages|.
     zx::vmo decompression_buffer_;

     // Size of |decompression_buffer_|, stashed at vmo creation time to avoid a syscall each time
     // the size needs to be queried.
     const size_t decompression_buffer_size_;

     // Maintains a connection to the external decompressor.
     std::unique_ptr<ExternalDecompressorClient> decompressor_client_;

     // Records all metrics for this instance of blobfs.
     BlobfsMetrics* metrics_ = nullptr;
   };

   explicit PageLoader(std::vector<std::unique_ptr<Worker>> workers);

   // Watchdog which triggers if any page faults exceed a threshold deadline.  This *must* come
   // before the loop below so that the loop, whose threads might have references to the watchdog, is
   // destroyed first.
   std::unique_ptr<fs_watchdog::WatchdogInterface> watchdog_;

   // Called for instantiating a thread local which statically assigns a worker to each thread.
   uint32_t AllocateWorker();

   // Set of resources required by a thread to serve the page. This *must* come before the loop below
   // since the threads for that loop may have references to the worker. Destruction of that loop
   // will ensure that all of the threads have stopped.
   std::vector<std::unique_ptr<Worker>> workers_;

   // Protects the worker_id_allocator_ from multiple pager thread races.
   std::mutex worker_allocation_lock_;
   // Incremented on the first call within each pager thread to allocate a worker.
   uint32_t worker_id_allocator_ __TA_GUARDED(worker_allocation_lock_) = 0;
 };

 }  // namespace blobfs

 #endif  // SRC_STORAGE_BLOBFS_PAGE_LOADER_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_STORAGE_BLOBFS_PAGE_LOADER_H_
	#define SRC_STORAGE_BLOBFS_PAGE_LOADER_H_

	#ifndef __Fuchsia__
	#error Fuchsia-only Header
	#endif

	#include <lib/async-loop/cpp/loop.h>
	#include <lib/async-loop/default.h>
	#include <lib/async/dispatcher.h>
	#include <lib/fzl/vmo-mapper.h>
	#include <lib/zx/pager.h>

	#include <functional>
	#include <memory>

	#include "src/storage/blobfs/blobfs_metrics.h"
	#include "src/storage/blobfs/compression/external_decompressor.h"
	#include "src/storage/blobfs/loader_info.h"
	#include "src/storage/blobfs/transaction_manager.h"
	#include "src/storage/blobfs/transfer_buffer.h"
	#include "src/storage/lib/vfs/cpp/paged_vfs.h"
	#include "src/storage/lib/watchdog/include/lib/watchdog/watchdog.h"

	namespace blobfs {

	// Wrapper enum for error codes supported by the zx_pager_op_range(ZX_PAGER_OP_FAIL) syscall, used
	// to communicate userpager errors to the kernel, so that the error can be propagated to the
	// originator of the page request (if required), and the waiting thread can be unblocked. We use
	// this wrapper enum instead of a raw zx_status_t as not all error codes are supported.
	enum class PagerErrorStatus : zx_status_t {
	kErrIO = ZX_ERR_IO,
	kErrDataIntegrity = ZX_ERR_IO_DATA_INTEGRITY,
	kErrBadState = ZX_ERR_BAD_STATE,
	// This value is not supported by zx_pager_op_range(). Instead, it is used to determine if the
	// zx_pager_op_range() call is required in the first place - PagerErrorStatus::kOK indicates no
	// error, so we don't make the call.
	kOK = ZX_OK,
	};

	constexpr PagerErrorStatus ToPagerErrorStatus(zx_status_t status) {
	switch (status) {
	case ZX_OK:
	return PagerErrorStatus::kOK;
	// ZX_ERR_IO_DATA_INTEGRITY is the only error code in the I/O class of errors that we
	// distinguish. For everything else return ZX_ERR_IO.
	case ZX_ERR_IO_DATA_INTEGRITY:
	return PagerErrorStatus::kErrDataIntegrity;
	case ZX_ERR_IO:
	case ZX_ERR_IO_DATA_LOSS:
	case ZX_ERR_IO_INVALID:
	case ZX_ERR_IO_MISSED_DEADLINE:
	case ZX_ERR_IO_NOT_PRESENT:
	case ZX_ERR_IO_OVERRUN:
	case ZX_ERR_IO_REFUSED:
	case ZX_ERR_PEER_CLOSED:
	return PagerErrorStatus::kErrIO;
	// Return ZX_ERR_BAD_STATE by default.
	default:
	return PagerErrorStatus::kErrBadState;
	}
	}

	// Applies the scheduling deadline profile to the given pager thread.
	void SetDeadlineProfile(const std::vector<zx::unowned_thread>& threads);

	// Encapsulates a user pager, its associated thread and transfer buffer.
	class PageLoader {
	public:
	DISALLOW_COPY_ASSIGN_AND_MOVE(PageLoader);

	// Resources needed for each worker thread.
	struct WorkerResources {
	WorkerResources(std::unique_ptr<TransferBuffer> uncompressed,
	std::unique_ptr<TransferBuffer> compressed)
	: uncompressed_buffer(std::move(uncompressed)), compressed_buffer(std::move(compressed)) {}

	std::unique_ptr<TransferBuffer> uncompressed_buffer;
	std::unique_ptr<TransferBuffer> compressed_buffer;
	};

	// Abstracts out how pages are supplied to the system.
	using PageSupplier = std::function<zx::result<>(uint64_t offset, uint64_t length,
	const zx::vmo& aux_vmo, uint64_t aux_offset)>;

	// Creates an instance of PageLoader.
	// A new thread is created and started to process page fault requests.
	// \|uncompressed_buffer\| is used to retrieve and buffer uncompressed data from the underlying
	// storage. \|resources\| is a set of resources needed for each individual \|Worker\| so only as many
	// pager threads are supported as there are sets of resources. \|decompression_buffer_size\| is the
	// size of the scratch buffer to use for decompression.
	[[nodiscard]] static zx::result<std::unique_ptr<PageLoader>> Create(
	std::vector<std::unique_ptr<WorkerResources>> resources, size_t decompression_buffer_size,
	BlobfsMetrics* metrics, DecompressorCreatorConnector* decompression_connector);

	// Invoked on a read request. Reads in the requested byte range [\|offset\|, \|offset\| + \|length\|)
	// for the inode associated with \|info->identifier\| into the \|transfer_buffer_\|, and then moves
	// those pages to the destination \|vmo\|. If \|verifier_info\| is not null, uses it to verify the
	// pages prior to transferring them to the destination vmo.
	//
	// How the pages are supplied to the caller is defined by the PageSupplier callback parameter.
	//
	// If an error is encountered, the error code is returned as a \|PagerErrorStatus\|. This error code
	// is communicated to the kernel with the zx_pager_op_range(ZX_PAGER_OP_FAIL) syscall.
	// \|PagerErrorStatus\| wraps the supported error codes for ZX_PAGER_OP_FAIL.
	// 1. ZX_ERR_IO - Failure while reading the required data from the block device.
	// 2. ZX_ERR_IO_DATA_INTEGRITY - Failure while verifying the contents read in.
	// 3. ZX_ERR_BAD_STATE - Any other type of failure which prevents us from successfully completing
	// the page request, e.g. failure while decompressing, or while transferring pages from the
	// transfer buffer etc.
	[[nodiscard]] PagerErrorStatus TransferPages(const PageSupplier& page_supplier, uint64_t offset,
	uint64_t length, const LoaderInfo& info);

	private:
	class Worker {
	public:
	DISALLOW_COPY_ASSIGN_AND_MOVE(Worker);
	// Creates a Worker resource. This resource is not thread-safe and should be associated with a
	// single thread, or protected via mutex, while serving page faults.
	// \|uncompressed_buffer\| is used to retrieve and buffer uncompressed data from the underlying
	// storage. \|compressed_buffer\| is used to retrieve and buffer compressed data from the
	// underlying storage. \|decompression_buffer_size\| is the size of the scratch buffer to use for
	// decompression.
	[[nodiscard]] static zx::result<std::unique_ptr<Worker>> Create(
	std::unique_ptr<WorkerResources> resources, size_t decompression_buffer_size,
	BlobfsMetrics* metrics, DecompressorCreatorConnector* decompression_connector);

	// See \|PageLoader::TransferPages()\| which simply selects which Worker to delegate the
	// actual work to.
	[[nodiscard]] PagerErrorStatus TransferPages(const PageLoader::PageSupplier& page_supplier,
	uint64_t offset, uint64_t length,
	const LoaderInfo& info);

	private:
	Worker(size_t decompression_buffer_size, BlobfsMetrics* metrics);

	PagerErrorStatus TransferChunkedPages(const PageLoader::PageSupplier& page_supplier,
	uint64_t offset, uint64_t length, const LoaderInfo& info);
	PagerErrorStatus TransferUncompressedPages(const PageLoader::PageSupplier& page_supplier,
	uint64_t offset, uint64_t length,
	const LoaderInfo& info);

	// Scratch buffer for pager transfers of uncompressed data.
	// NOTE: Per the constraints imposed by \|zx_pager_supply_pages\|, the VMO owned by this buffer
	// needs to be unmapped before calling \|zx_pager_supply_pages\|. Map
	// \|uncompressed_transfer_buffer_.vmo()\| only when an explicit address is required, e.g. for
	// verification, and unmap it immediately after.
	std::unique_ptr<TransferBuffer> uncompressed_transfer_buffer_;

	// Scratch buffer for pager transfers of compressed data.
	// Unlike the above transfer buffer, this never needs to be unmapped since we will be calling
	// \|zx_pager_supply_pages\| on the \|decompression_buffer_\|.
	std::unique_ptr<TransferBuffer> compressed_transfer_buffer_;

	// A persistent mapping for \|compressed_transfer_buffer_\|.
	fzl::VmoMapper compressed_mapper_;

	// This is the buffer that can be written to by the other end of the
	// \|decompressor_client_\| connection. The contents are not to be trusted and
	// may be changed at any time, so they need to be copied out prior to
	// verification.
	zx::vmo sandbox_buffer_;

	// Scratch buffer for decompression.
	// NOTE: Per the constraints imposed by \|zx_pager_supply_pages\|, this needs to be unmapped
	// before calling \|zx_pager_supply_pages\|.
	zx::vmo decompression_buffer_;

	// Size of \|decompression_buffer_\|, stashed at vmo creation time to avoid a syscall each time
	// the size needs to be queried.
	const size_t decompression_buffer_size_;

	// Maintains a connection to the external decompressor.
	std::unique_ptr<ExternalDecompressorClient> decompressor_client_;

	// Records all metrics for this instance of blobfs.
	BlobfsMetrics* metrics_ = nullptr;
	};

	explicit PageLoader(std::vector<std::unique_ptr<Worker>> workers);

	// Watchdog which triggers if any page faults exceed a threshold deadline. This must come
	// before the loop below so that the loop, whose threads might have references to the watchdog, is
	// destroyed first.
	std::unique_ptr<fs_watchdog::WatchdogInterface> watchdog_;

	// Called for instantiating a thread local which statically assigns a worker to each thread.
	uint32_t AllocateWorker();

	// Set of resources required by a thread to serve the page. This must come before the loop below
	// since the threads for that loop may have references to the worker. Destruction of that loop
	// will ensure that all of the threads have stopped.
	std::vector<std::unique_ptr<Worker>> workers_;

	// Protects the worker_id_allocator_ from multiple pager thread races.
	std::mutex worker_allocation_lock_;
	// Incremented on the first call within each pager thread to allocate a worker.
	uint32_t worker_id_allocator_ __TA_GUARDED(worker_allocation_lock_) = 0;
	};

	} // namespace blobfs

	#endif // SRC_STORAGE_BLOBFS_PAGE_LOADER_H_