blob: 495bf70d761ca26b9dc632c9a5f1f2a43d9007de [file] [log] [blame]
// 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.
#include <lib/vfs/cpp/node.h>
#include <lib/zx/vmo.h>
#include <zircon/availability.h>
#include <zircon/status.h>
#include <cstdint>
namespace vfs {
// A file node backed by a range of bytes in a VMO.
// The file has a fixed size specified at creating time; it does not grow or shrink even when
// written into.
// This class is thread-safe.
class VmoFile final : public Node {
// TODO( Remove deprecated enum constants and type aliases below.
// Specifies the desired behavior of writes.
enum class WriteMode : vfs_internal_write_mode_t {
// The VmoFile is read only.
// The VmoFile will be writable.
READ_ONLY ZX_REMOVED_SINCE(1, 19, 20, "Use kReadOnly instead.") = kReadOnly,
WRITABLE ZX_REMOVED_SINCE(1, 19, 20, "Use kWritable instead.") = kWritable,
// Specifies the default behavior when a client asks for the file's underlying VMO, but does not
// specify if a duplicate handle or copy-on-write clone is required.
// *NOTE*: This does not affect the behavior of requests that specify the required sharing mode.
// Requests for a specific sharing mode will be fulfilled as requested.
enum class DefaultSharingMode : vfs_internal_sharing_mode_t {
// Will return `ZX_ERR_NOT_SUPPORTED` if a sharing mode was not specified in the request.
// The VMO handle is duplicated for each client.
// This is appropriate when it is okay for clients to access the entire
// contents of the VMO, possibly extending beyond the pages spanned by the
// file.
// This mode is significantly more efficient than |CLONE_COW| and should be
// preferred when file spans the whole VMO or when the VMO's entire content
// is safe for clients to read.
// The VMO range spanned by the file is cloned on demand, using
// copy-on-write semantics to isolate modifications of clients which open
// the file in a writable mode.
// This is appropriate when clients need to be restricted from accessing
// portions of the VMO outside of the range of the file and when file
// modifications by clients should not be visible to each other.
NONE ZX_REMOVED_SINCE(1, 19, 20, "Use kNone instead.") = kNone,
DUPLICATE ZX_REMOVED_SINCE(1, 19, 20, "Use kDuplicate instead.") = kDuplicate,
CLONE_COW ZX_REMOVED_SINCE(1, 19, 20, "Use kCloneCow instead.") = kCloneCow,
using WriteOption ZX_REMOVED_SINCE(1, 19, 20, "Use WriteMode instead.") = WriteMode;
using Sharing ZX_REMOVED_SINCE(1, 19, 20, "Use DefaultSharingMode instead.") = DefaultSharingMode;
// Creates a file node backed by a VMO.
VmoFile(zx::vmo vmo, size_t length, WriteMode write_option = WriteMode::kReadOnly,
DefaultSharingMode vmo_sharing = DefaultSharingMode::kDuplicate)
: VmoFile(vmo.release(), length, write_option, vmo_sharing) {}
using Node::Serve;
// Returns a borrowed handle to the VMO backing this file.
zx::unowned_vmo vmo() const { return vmo_->borrow(); }
VmoFile(zx_handle_t vmo_handle, size_t length, WriteMode write_option,
DefaultSharingMode vmo_sharing)
: Node(CreateVmoFile(vmo_handle, length, write_option, vmo_sharing)),
vmo_(zx::unowned_vmo{vmo_handle}) {}
// The underlying node is responsible for closing `vmo_handle` when the node is destroyed.
static vfs_internal_node_t* CreateVmoFile(zx_handle_t vmo_handle, size_t length,
WriteMode write_option,
DefaultSharingMode vmo_sharing) {
vfs_internal_node_t* vmo_file;
ZX_ASSERT(vfs_internal_vmo_file_create(vmo_handle, static_cast<uint64_t>(length),
&vmo_file) == ZX_OK);
return vmo_file;
zx::unowned_vmo vmo_; // Cannot outlive underlying node.
} // namespace vfs