// 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.

// !!! THIS FILE IS NOT YET USED !!!
// See //zircon/system/public/zircon/syscalls.banjo.
// !!! THIS FILE IS NOT YET USED !!!

library zz;

[Transport="Syscall"]
protocol Vmo {
    /// Create a VM object.
    [Out1="handle<vmo>:acquire"]
    Create(uint64 size, uint32 options) -> (status status, handle<vmo> out);

    // TODO(scottmg): This syscall is very weird, it's currently:
    //    (handle, buffer, offset, buffer_size)
    // rather than:
    //    (handle, buffer, buffer_size, offset)
    // which means the vector<byte> buffer won't work. Unfortunately offset and
    // buffer_size have the same underlying type, so moving them will be
    // error-prone.
    /// Read bytes from the VMO.
    [Blocking,
     In0="handle<vmo>:rights=READ",
     In1="mutable<vector<byte>>"]
    Read(handle<vmo> handle, vector<byte> buffer, uint64 offset) -> (status status);

    // TODO(scottmg): Same probelm as Read() above.
    /// Write bytes to the VMO.
    [Blocking,
     In0="handle<vmo>:rights=WRITE"]
    Write(handle<vmo> handle, vector<byte> buffer, uint64 offset) -> (status status);

    // TODO(ZX-2967): No rights required?
    /// Read the current size of a VMO object.
    GetSize(handle<vmo> handle) -> (status status, uint64 size);

    /// Resize a VMO object.
    [In0="handle<vmo>:rights=WRITE"]
    SetSize(handle<vmo> handle, uint64 size) -> (status status);

    /// Perform an operation on a range of a VMO.
    [Blocking,
     In4="mutable<vector<byte>>"]
    OpRange(handle<vmo> handle, uint32 op, uint64 offset, uint64 size, vector<byte> buffer) ->
        (status status);

    /// Create a child of a VM Object.
    [In0="handle<vmo>:rights=DUPLICATE,READ",
     Out1="handle<vmo>:acquire"]
    CreateChild(handle<vmo> handle, uint32 options, uint64 offset, uint64 size) ->
        (status status, handle<vmo> out);

    /// Set the caching policy for pages held by a VMO.
    [In0="handle<vmo>:rights=MAP"]
    SetCachePolicy(handle<vmo> handle, uint32 cache_policy) -> (status status);

    // TODO(ZX-2967): handle: No rights required, ZX_RIGHT_EXECUTE added to dup out
    // TODO(ZX-2967): vmex == ZX_HANDLE_INVALID also accepted.
    /// Add execute rights to a VMO.
    [In0="handle<vmo>:release_always",
     In1="handle<resource>:kind=VMEX",
     Out1="handle:acquire"]
    ReplaceAsExecutable(handle<vmo> handle, handle<resource> vmex) ->
        (status status, handle<vmo> out);

    [In0="handle<bti>:rights=MAP",
     Out1="handle<vmo>:acquire"]
    CreateContiguous(handle<bti> bti, usize size, uint32 alignment_log2) ->
        (status status, handle<vmo> out);

    /// Create a VM object referring to a specific contiguous range of physical memory.
    [In0="handle<resource>:kind=MMIO",
     Out1="handle<vmo>:acquire"]
    CreatePhysical(handle<resource> resource, paddr paddr, usize size) ->
        (status status, handle<vmo> out);
};