sdk/fidl/fuchsia.sysmem2/error.fidl

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

/// Regardless of which error code, any client retries should be very limited in
/// number, if any.
///
/// A Error value should never be stored in a zx_status_t, since positive values
/// in zx_status_t are deprecated.
@available(added=19)
type Error = flexible enum : uint32 {
    /// This is not a valid error value in this error enum. The server will
    /// never send this value as a failure code. This value is not treated as
    /// "success". In some languages, a locally default-initialized Error
    /// instance will have this value until it is initialized with a valid
    /// positive error code.
    INVALID = 0;

    /// Unspecified error.
    ///
    /// This error code is used when no other error code applies, and the error
    /// is probably not due to problematic messages sent to the server via the
    /// channel delivering this error.
    ///
    /// This error should be handled by the client as a generic error.
    ///
    /// As one example, this error is used when a different client channel has
    /// closed from the client end unexpectedly (without sending
    /// [`fuchsia.sysmem2/Node.Release`] first), thereby causing failure of any
    /// nodes in the same tree or sub-tree. In this usage, the main thing that's
    /// relevant is it isn't the receiving client's "fault" - no reason to be
    /// more specific since there's probably nothing the receiving client could
    /// do about the error, at least not directly.
    ///
    /// As another example, this error can be used if a syscall that is normally
    /// expected to succeed fails unexpectedly, and there's no identified reason
    /// to "blame" the client.
    ///
    /// A client should never require / depend on a particular cause of error
    /// continuing to result in UNSPECIFIED, as any particular error cause can
    /// potentially start resulting in a more specific error code in future.
    //
    // Previously conveyed using ZX_ERR_INTERNAL.
    UNSPECIFIED = 1;

    /// A required field wasn't set or a specified value was invalid. See the
    /// log for more info.
    ///
    /// This is also used when a message is received from the client in the
    /// wrong order or in some way inconsistent with protocol rules.
    //
    // Previously conveyed using ZX_ERR_INVALID_ARGS.
    PROTOCOL_DEVIATION = 2;

    /// A client-specified object or ID was not found.
    //
    // Previously conveyed using ZX_ERR_NOT_FOUND.
    NOT_FOUND = 3;

    /// The object handle doesn't have sufficient rights to perform the request.
    //
    // Previously conveyed using ZX_ERR_ACCESS_DENIED.
    HANDLE_ACCESS_DENIED = 4;

    /// The allocation could not be satisfied due to lack of available memory.
    ///
    /// The memory exhaustion can be specific to the heap that was selected
    /// during constraints aggregation, so in some cases, this error can happen
    /// despite normal system RAM not being near exhaustion, depending on
    /// configured and selected heap(s).
    //
    // Previously conveyed using ZX_ERR_NO_MEMORY.
    NO_MEMORY = 5;

    /// The request is valid but cannot be satisfied, perhaps due to hardware
    /// limitations. This happens if participants involved in this allocation
    /// have incompatible constraints (empty intersection, roughly speaking).
    /// See the log for more info. In cases where a participant could
    /// potentially be treated as optional, see [`BufferCollectionTokenGroup`].
    ///
    /// This can also happen if there aren't enough buffers in a pre-existing
    /// collection to satisfy an additional token (including sub-tree of derived
    /// tokens) created with [`fuchsia.sysmem2/BufferCollection.AttachToken`].
    ///
    /// This can also happen if a client's node is under a group and a different
    /// group child is selected instead.
    //
    // This was previously conveyed with ZX_ERR_NOT_SUPPORTED, but that error
    // code isn't a perfect semantic match.
    CONSTRAINTS_INTERSECTION_EMPTY = 6;

    /// Allocation hasn't been attempted yet. Calling
    /// [`fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated`] would
    /// (likely) block.
    //
    // This was previously conveyed with ZX_ERR_UNAVAILABLE, but that error
    // code isn't a perfect semantic match.
    PENDING = 7;

    /// Too many `BufferCollectionTokenGroup` child token selection combinations
    /// exist and were considered, causing sysmem to give up on allocating
    /// rather than enumerate the rest.
    //
    // This was prevously conveyed with ZX_ERR_OUT_OF_RANGE, but that error code
    // isn't a perfect semantic match.
    TOO_MANY_GROUP_CHILD_COMBINATIONS = 8;
};