src/devices/bind/fuchsia.sysmem.heap/fuchsia.sysmem.heap.bind

// Copyright 2024 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.heap;

// To specify a specific heap, the heap type is specified by a bind string, and
// the heap instance ID is specified by an unsigned 64 bit integer that only
// needs to be unique within the heap type, and only per boot.
//
// For heap types that refer to a singleton heap of that type per device, the
// heap instance ID can be un-set (in FIDL) or set to 0. The heap instance ID
// has no associated bind string - it's just mentioned here for context.

// Heap type bind strings (so far) are of the form
// fuchsia.sysmem.heap[.<namespace>].HEAP_TYPE.<type_name> or
// fuchsia.<vendor|platform>.platform.sysmem.heap[.<namespace>].HEAP_TYPE.<type_name> or
// <vendor>[.<namespace0>].sysmem.heap[.<namespace1>].HEAP_TYPE.<type_name>
//
// A bind string is created by creating a bind library (in any repo) with
// "sysmem.heap" in the library name, defining an enum named HEAP_TYPE with the
// heap types listed as values in the enum. All heap bind strings in the fuchsia
// repo will have "namespace0" empty (consistent with the patterns above under
// fuchsia that lack a "namespace0").
//
// All heap type strings (outside of tests) should include "sysmmem.heap" as
// part of the bind library name, and use "HEAP_TYPE" as the name of the enum.
//
// This allows for distributed allocation of heap type names, while keeping the
// chance of collision low enough, as long as the <vendor>, platform, and
// namespace portions are allocated sensibly. Please no camping on names that
// aren't plausibly yours to camp on.
//
// Some general non-vendor-specific heap types are defined in this file, and
// have the form fuchsia.sysmem.heap.HEAP_TYPE.<type_name>, for example
// fuchsia.sysmem.heap.HEAP_TYPE.SYSTEM_RAM. These types can be used on various
// devices from various vendors.
//
// For some current vendor-specific heap type name definitions, definitions are
// in the fuchsia repo. Because the fuchsia repo requires bind lib names to
// start with "fuchsia", the second form above is used for vendor-specific
// heap types defined in the fuchsia repo. If these heap name definitions later
// move to a different repo in future, they can be renamed to start with
// <vendor> instead (3rd form above is recommended). At runtime a heap type can
// be referenced by more than one name (support for this is currently TODO), to
// allow for soft-transition renames.

// Heap type names that don't conform to the bind string naming scheme or don't
// use a bind lib to define heap type names may break without warning. For
// example, any namespace portion(s) must be lowercase without any whitespace.
// Using this bind string mechanism and specific forms described above to define
// heap type strings is strongly recommended in "steady state", but in some
// temporary situations, it may make sense to temporarily specify a bind string
// that is just a string, without reference to a bind library or its generated
// code.
//
// For example this can make sense if a heap type name is being changed in a
// non-breaking way. At some stage during such a rename, a heap implementation
// may want to continue registering/accepting a deprecated + removed (but still
// reserved) heap name, without that name being a currently-defined bind string.
// This way, binaries wouldn't break, but on the next build of participant code,
// the build would fail when the participant tries to use the removed name (from
// the bind lib generated code), and the fix can be made fairly obvious by
// leaving a helpful and searchable comment in the .bind lib file that used to
// have the now-removed name.

// We don't define a heap ID in this bind lib. The fuchsia.sysmem2.Heap FIDL
// table has an "id" field for the heap ID. Heap IDs are typically either 0 for
// a heap type corresponding to a singleton heap, or dynamically assigned and
// discovered per-boot. Most cases involving fixed heap IDs would make more
// sense as separate heap types, or as a logical single heap that uses multiple
// separate chunks of space internally.
//
// In the event that fixed heap IDs make the most sense for a future heap type,
// the bind lib that defines the heap types for that platform can choose to
// define fixed heap IDs in that bind lib as well. The recommended name for that
// uint or uint64 is "HEAP_ID". Using a uint64 is recommended if supported in
// bind libs by then, but uint can work fine for fixed heap IDs. The heap ID is
// a uint64 in FIDL, so a uint(32) in a bind lib can get zero-extended to uint64
// at point of use.

enum HEAP_TYPE {
    // Generic RAM.
    //
    // This is the default when no participant sets
    // fuchsia.sysmem2.BufferMemoryConstraints.permitted_heaps.
    //
    // Depending on device configuration, this heap can be capable of allocating
    // both non-physically-contiguous and physically-contiguous buffers.
    //
    // Currently this is a singleton, with a single logical SYSTEM_RAM heap with
    // id 0.
    //
    // Typically the SYSTEM_RAM heap is not usable for allocating when
    // secure_required true. An initiator specifying secure_required true can
    // permit any is_secure true heap by leaving permitted_heaps un-set and
    // setting inaccessible_domain_supported to true. This requires at least one
    // participant to list a specific is_secure true heap. Currently all
    // is_secure true heaps are vendor-specific, with corresponding bind strings
    // defined in separate vendor-specific bind libs, with their own separate
    // HEAP_TYPE enums.
    SYSTEM_RAM,

    // Heap used for display framebuffer. This is used by display drivers
    // limited to a single framebuffer located at a specific physical address.
    // The framebuffer heap makes it possible to create buffer collections for
    // the framebuffer and enables sysmem support in these drivers.
    //
    // Currently this is a singleton, with a single logical FRAMEBUFFER heap
    // with id 0.
    FRAMEBUFFER,
};