blob: e2f5fcef0da71b3373adb08ecea6676ccc3bc6b1 [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.
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) -> ();