zircon/vdso/iob.fidl

// Copyright 2023 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 zx;

/// zx_iob_allocate_id() options.
@next
type IobAllocateIdOptions = flexible bits : uint32 {};

@transport("Syscall")
closed protocol Iob {
    /// ## Summary
    ///
    /// Create an IOBuffer with a set of options.
    ///
    /// ## Declaration
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_iob_create(uint64_t options,
    ///                           const zx_iob_region_t* regions,
    ///                           uint32_t region_count,
    ///                           zx_handle_t* ep0_out,
    ///                           zx_handle_t* ep1_out);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_iob_create()` creates an IOBuffer, a memory object designed for
    /// efficient point-to-point communication. An IOBuffer can be thought
    /// of as an abstraction over a shared buffer backing a specific container
    /// with (optionally kernel-mediated) reads and writes that maintain data
    /// integrity and enforce permissions.
    ///
    /// An IOBuffer may have multiple regions, specified by *region_count*.
    /// Each region may be set to support varying access patterns or permissions
    /// configured by *regions*.
    ///
    /// If a region is configured for mediated access, then it will be created
    /// with the associated container initialized.
    ///
    /// ### Region Descriptions
    ///
    /// The geometry and configuration of a region are specified by a `zx_iob_region_t`
    /// region description structure. The base structure includes fields that are common
    /// to all region types.
    ///
    /// ```C++
    /// struct zx_iob_region_t {
    ///   zx_iob_region_type_t type;
    ///   zx_iob_access_t access;
    ///   uint64_t size;
    ///   zx_iob_discipline_t discipline;
    ///   union {
    ///     zx_iob_region_private_t private_region;
    ///     uint8_t max_extension[4 * 8];
    ///   };
    /// };
    /// ```
    ///
    /// *type* specifies the type of the region and memory object backing it.
    /// The valid types are:
    ///   - ZX_IOB_REGION_TYPE_PRIVATE: a region backed by a private memory
    ///     uniquely owned by the IOB.
    ///
    /// *access* specifies the access control modifiers for each endpoint. It
    /// must be a combination of one or more of:
    ///
    ///  - `ZX_IOB_ACCESS_EP0_CAN_MAP_READ` to grant endpoint 0 to ability to map the region as readable
    ///  - `ZX_IOB_ACCESS_EP0_CAN_MAP_WRITE` to grant endpoint 0 to ability to map the region as writable
    ///  - `ZX_IOB_ACCESS_EP1_CAN_MAP_READ` to grant endpoint 1 to ability to map the region as readable
    ///  - `ZX_IOB_ACCESS_EP1_CAN_MAP_WRITE` to grant endpoint 1 to ability to map the region as writable
    ///
    /// *size* is the requested size of the region in bytes. The size will be
    ///   rounded up to the next system page size boundary, as reported by
    ///   zx_system_get_page_size(). Use `zx_object_get_info` with topic
    ///   `ZX_INFO_IOB_REGIONS` to determine the actual size of the region.
    ///
    /// *discipline* specifies the memory access discipline to employ for
    ///  kernel-mediated operations. The valid disciplines are:
    ///  - ZX_IOB_DISCIPLINE_TYPE_NONE: a free form region with no kernel mediated operations.
    ///
    /// ### Region Types
    /// #### ZX_IOB_REGION_TYPE_PRIVATE
    ///
    /// Specifies a region backed by a private memory object uniquely owned by the IOB.
    /// This memory object is only accessible through operations on, and mappings of,
    /// the owning IOB.
    ///
    /// ```
    /// struct zx_iob_region_private_t {
    ///   uint64_t options;
    /// };
    /// ```
    ///
    /// *options* must be 0
    ///
    /// ### Discipline Types
    ///
    /// See `zx_iob_discipline_type_t` for more detail.
    ///
    /// ## Return value
    ///
    /// `zx_iob_create()` returns `ZX_OK` on success. In the event of failure,
    /// a negative error value is returned.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_INVALID_ARGS`  *ep_out0* or *ep_out1* is an invalid pointer or
    /// NULL, *options* is any value other than 0, or the regions configuration
    /// is invalid (e.g., if the region is inaccessible, being neither
    /// map-writable or configured for mediated-access, or if the discipline is
    /// invalid).
    ///
    /// `ZX_ERR_NO_MEMORY`  Failure due to lack of memory to allocated the
    /// requested buffers.
    strict Create(struct {
        options uint64;
        @voidptr
        regions vector<byte>:IOB_MAX_REGIONS;
    }) -> (resource struct {
        ep0_out Handle;
        ep1_out Handle;
    }) error Status;

    /// ## Summary
    ///
    /// Allocates an ID out of an IOBuffer region of discipline
    /// `ZX_IOB_DISCIPLINE_TYPE_ID_ALLOCATOR`.
    ///
    /// ## Declaration
    /// ```c
    /// #include <zircon/syscalls-next.h>
    ///
    /// zx_status_t zx_iob_allocate_id(zx_handle_t handle,
    ///                                zx_iob_allocate_id_options_t options,
    ///                                uint32_t region_index,
    ///                                const void* blob,
    ///                                uint64_t blob_size,
    ///                                uint32_t* id);
    /// ```
    ///
    /// ## Description
    ///
    /// A new ID is allocated for the provided blob from the associated
    /// container backing an IOBuffer region of discipline
    /// `ZX_IOB_DISCIPLINE_TYPE_ID_ALLOCATOR`,
    ///
    /// The IOBuffer handle used to interact with the region must admit mediated
    /// write access.
    ///
    /// ## Return value
    ///
    /// On success, `zx_iob_allocate_id()` returns `ZX_OK` and populates `id`
    /// with the allocated ID.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_OUT_OF_RANGE`  `region_index` exceeded the maximum region
    /// index.
    ///
    /// `ZX_ERR_WRONG_TYPE`  The corresponding region is not of the
    /// `ZX_IOB_DISCIPLINE_TYPE_ID_ALLOCATOR` discipline.
    ///
    /// `ZX_ERR_INVALID_ARGS`  `options` was nonzero (there are no non-default
    /// options supported at this time).
    ///
    /// `ZX_ERR_ACCESS_DENIED`  The IOB handle does not have write permissions,
    /// or the corresponding region does not have mediated write permissions.
    ///
    /// `ZX_ERR_NO_MEMORY`  The ID allocator region has run out of memory from
    /// which to allocate new IDs. Note that this unrelated to the state of
    /// system memory.
    ///
    /// `ZX_ERR_IO_DATA_INTEGRITY`  The ID allocator region has been corrupted.
    @next
    strict AllocateId(resource struct {
        handle Handle:IOB;
        options IobAllocateIdOptions;
        region_index uint32;
        @voidptr
        blob vector<byte>:MAX;
    }) -> (struct {
        id uint32;
    }) error Status;
};