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

library fuchsia.sysmem;

using zx;

/// Manages resources on a specific sysmem heap.
///
/// Needs Layout = "Simple" because used with "FIDL Simple C Bindings".
[Layout = "Simple"]
protocol Heap {
    /// Request a new memory allocation of `size` on heap.
    /// For heaps which don't permit CPU access to the buffer data, this
    /// will create a VMO with an official size, but which never has any
    /// physical pages.  For such heaps, the VMO is effectively used as
    /// an opaque buffer identifier.
    ///
    /// Heaps should defer allocation of any associated resources until
    /// CreateResource(), because the caller of AllocateVmo() may simply
    /// delete the returned VMO with no further notification to the heap.
    /// In contrast, after CreateResource(), the caller guarantees that
    /// DestroyResource() or heap channel closure will occur.
    ///
    /// The caller guarantees that CreateResource() will be called prior
    /// to the returned VMO or any associated child VMO being used.
    AllocateVmo(uint64 size) -> (zx.status s, handle<vmo>? vmo);

    /// Create resources and associate heap-specific resources with the
    /// passed-in VMO. Resources can be hardware specific and their
    /// lifetime don't have to be tied to `vmo`. `vmo` must be a VMO
    /// (or a direct or indirect child of a VMO) acquired through a call
    /// to AllocateVmo method above.  If the passed-in vmo is a child VMO,
    /// its size must match the size of the parent VMO created by
    /// AllocateVmo().  For heaps that permit CPU access, the passed-in
    /// VMO must not have a copy-on-write relationship with the parent
    /// VMO, but rather a pass-through relationship. Successful return
    /// status indicate that Heap has established a mapping between
    /// VMO and hardware specific resources.
    ///
    /// The returned id must be passed to DestroyResource() later when
    /// resources associated with VMO are no longer needed, unless the
    /// heap channel closes first.
    ///
    /// The heap must not own/keep a handle to VMO, or any derived child
    /// VMO, or any VMAR mapping to VMO, as any of those would keep VMO
    /// alive beyond all sysmem participant usages of the vmo; instead
    /// the heap can get the vmo's koid for the heap's mapping.
    CreateResource(handle<vmo> vmo) -> (zx.status s, uint64 id);

    /// Destroy previously created resources.
    DestroyResource(uint64 id) -> ();
};