sdk/fidl/fuchsia.mem/buffer.fidl

// Copyright 2017 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.mem;

using zx;

/// A buffer for data whose size is not necessarily a multiple of the page
/// size.
///
/// DEPRECATED: This type is superfluous and deprecated. Instead of using this type,
/// use a zx.Handle:VMO object and store the size of the contents in the ZX_PROP_VMO_CONTENT_SIZE
/// property.
// TODO(https://fxbug.dev/42166353): Remove all users of this type, then remove
// this type.
type Buffer = resource struct {
    /// The vmo that contains the buffer.
    vmo zx.Handle:VMO;

    /// The number of bytes in the buffer.
    ///
    /// The content of the buffer begin at the start of the VMO and continue
    /// for `size` bytes. To specify a range of bytes that do not start at
    /// the beginning of the VMO, use `Range` rather than buffer.
    ///
    /// This size must not be greater than the physical size of the VMO.
    size uint64;
};

/// Binary data that might be stored inline or in a VMO.
///
/// Useful for performance-sensitive protocols that sometimes receive small
/// amounts of binary data (i.e., which is more efficient to provide using
/// `bytes`) but also need to support arbitrary amounts of data (i.e., which
/// need to be provided out-of-line in a `Buffer`).
type Data = flexible resource union {
    /// The binary data provided inline in the message.
    1: bytes vector<uint8>:MAX;

    /// The binary data provided out-of-line in a `Buffer`.
    2: buffer Buffer;

    // TODO(https://fxbug.dev/42166353): Add a VMO entry and teach all users
    // of this type how to store data in it.
};