zircon/vdso/iob.fidl - fuchsia - Git at Google

 // 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 {};

 type IobWriteOptions = flexible bits : uint64 {};

 @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,
     ///                           size_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[32];
     ///   };
     /// };
     /// ```
     ///
     /// *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_EP0_CAN_MEDIATED_READ` to grant endpoint 0 ability to perform mediated reads
     ///  - `ZX_IOB_ACCESS_EP0_CAN_MEDIATED_WRITE` to grant endpoint 0 ability to perform mediated writes
     ///  - `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
     ///  - `ZX_IOB_ACCESS_EP1_CAN_MEDIATED_READ` to grant endpoint 1 ability to perform mediated reads
     ///  - `ZX_IOB_ACCESS_EP1_CAN_MEDIATED_WRITE` to grant endpoint 1 ability to perform mediated writes
     ///
     /// *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.
     ///
     /// ```c
     /// struct zx_iob_region_private_t {
     ///   uint32_t options;
     ///   uint32_t padding1;
     ///   uint64_t padding2[3];
     /// };
     /// ```
     ///
     /// *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.
     ///
     /// `ZX_ERR_OUT_OF_RANGE`  The number of regions exceeds the maximum (64).
     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;

     /// ## Summary
     ///
     /// Performs a mediated write to an IOBuffer region.
     ///
     /// ## Declaration
     /// ```c
     /// #include <zircon/syscalls/iob.h>
     ///
     /// zx_status_t zx_iob_write(zx_handle_t handle,
     ///                          zx_iob_write_options_t options,
     ///                          uint32_t region_index,
     ///                          const zx_iovec_t* vectors,
     ///                          size_t num_vectors);
     /// ```
     ///
     /// ## Description
     ///
     /// Performs a mediated write to an IOBuffer region.
     ///
     /// `options` must be zero.
     ///
     /// The IOBuffer handle used to interact with the region must admit mediated write access.
     ///
     /// There is a limit of 65535 bytes including any headers that the discipline might mandate, and
     /// there can be no more than 8 vectors.
     ///
     /// ## Return value
     ///
     /// On success, the data is written to the specified region according to the semantics of the
     /// discipline.
     ///
     /// ## Errors
     ///
     /// `ZX_ERR_ACCESS_DENIED`  The IOB handle does not have write permissions,
     /// or the corresponding region does not have mediated write permissions.
     ///
     /// `ZX_ERR_BAD_HANDLE`  *handle* is not a valid handle.
     ///
     /// `ZX_ERR_INVALID_ARGS`  `options` was nonzero (there are no non-default options supported at
     /// this time), the amount of data to write exceeds the limit, or the vectors are invalid.
     ///
     /// `ZX_ERR_IO_DATA_INTEGRITY`  The region has been corrupted.
     ///
     /// `ZX_ERR_NOT_FOUND`  A vector is invalid (e.g. points to invalid memory).
     ///
     /// `ZX_ERR_NO_SPACE`  The region has insufficient space to write the message.
     ///
     /// `ZX_ERR_OUT_OF_RANGE`  `region_index` exceeded the maximum region index.
     ///
     /// `ZX_ERR_WRONG_TYPE`  The handle is not an IOBuffer handle, or the corresponding region is not
     /// of the required discipline.
     strict Writev(resource struct {
         handle Handle:IOB;
         options IobWriteOptions;
         region_index uint32;
         vectors vector<Iovec>:MAX;
     }) -> () error Status;

     /// ## Summary
     ///
     /// Creates a shared region that can be used with multiple IOBuffer objects.
     ///
     /// ## Declaration
     /// ```c
     /// #include <zircon/syscalls-next.h>
     ///
     /// zx_status_t zx_iob_create_shared_region(uint64_t options,
     ///                                         uint64_t size,
     ///                                         zx_handle_t* out);
     /// ```
     ///
     /// ## Description
     ///
     /// Creates a shared region that can be used with multiple IOBuffer objects.
     ///
     /// `options` must be zero. `size` must be a multiple of the page size.
     ///
     /// ## Return value
     ///
     /// On success, `ZX_OK` is returned and `out` will be populated with a new handle.
     ///
     /// ## Errors
     ///
     /// `ZX_ERR_ACCESS_DENIED` The proess does not have permissions to create shared IOBuffer
     /// regions.
     ///
     /// `ZX_ERR_INVALID_ARGS` `options` was nonzero (there are no non-default options supported at
     /// this time), or `size` was zero or not a multiple of the page size.
     ///
     /// `ZX_ERR_NO_MEMORY` Failure due to lack of memory to allocate the shared region.
     @next
     strict CreateSharedRegion(struct {
         options uint64;
         size uint64;
     }) -> (resource struct {
         out Handle;
     }) error Status;
 };
	// 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 {};

	type IobWriteOptions = flexible bits : uint64 {};

	@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,
	/// size_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[32];
	/// };
	/// };
	/// ```
	///
	/// 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_EP0_CAN_MEDIATED_READ` to grant endpoint 0 ability to perform mediated reads
	/// - `ZX_IOB_ACCESS_EP0_CAN_MEDIATED_WRITE` to grant endpoint 0 ability to perform mediated writes
	/// - `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
	/// - `ZX_IOB_ACCESS_EP1_CAN_MEDIATED_READ` to grant endpoint 1 ability to perform mediated reads
	/// - `ZX_IOB_ACCESS_EP1_CAN_MEDIATED_WRITE` to grant endpoint 1 ability to perform mediated writes
	///
	/// 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.
	///
	/// ```c
	/// struct zx_iob_region_private_t {
	/// uint32_t options;
	/// uint32_t padding1;
	/// uint64_t padding2[3];
	/// };
	/// ```
	///
	/// 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.
	///
	/// `ZX_ERR_OUT_OF_RANGE` The number of regions exceeds the maximum (64).
	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;

	/// ## Summary
	///
	/// Performs a mediated write to an IOBuffer region.
	///
	/// ## Declaration
	/// ```c
	/// #include <zircon/syscalls/iob.h>
	///
	/// zx_status_t zx_iob_write(zx_handle_t handle,
	/// zx_iob_write_options_t options,
	/// uint32_t region_index,
	/// const zx_iovec_t* vectors,
	/// size_t num_vectors);
	/// ```
	///
	/// ## Description
	///
	/// Performs a mediated write to an IOBuffer region.
	///
	/// `options` must be zero.
	///
	/// The IOBuffer handle used to interact with the region must admit mediated write access.
	///
	/// There is a limit of 65535 bytes including any headers that the discipline might mandate, and
	/// there can be no more than 8 vectors.
	///
	/// ## Return value
	///
	/// On success, the data is written to the specified region according to the semantics of the
	/// discipline.
	///
	/// ## Errors
	///
	/// `ZX_ERR_ACCESS_DENIED` The IOB handle does not have write permissions,
	/// or the corresponding region does not have mediated write permissions.
	///
	/// `ZX_ERR_BAD_HANDLE` handle is not a valid handle.
	///
	/// `ZX_ERR_INVALID_ARGS` `options` was nonzero (there are no non-default options supported at
	/// this time), the amount of data to write exceeds the limit, or the vectors are invalid.
	///
	/// `ZX_ERR_IO_DATA_INTEGRITY` The region has been corrupted.
	///
	/// `ZX_ERR_NOT_FOUND` A vector is invalid (e.g. points to invalid memory).
	///
	/// `ZX_ERR_NO_SPACE` The region has insufficient space to write the message.
	///
	/// `ZX_ERR_OUT_OF_RANGE` `region_index` exceeded the maximum region index.
	///
	/// `ZX_ERR_WRONG_TYPE` The handle is not an IOBuffer handle, or the corresponding region is not
	/// of the required discipline.
	strict Writev(resource struct {
	handle Handle:IOB;
	options IobWriteOptions;
	region_index uint32;
	vectors vector<Iovec>:MAX;
	}) -> () error Status;

	/// ## Summary
	///
	/// Creates a shared region that can be used with multiple IOBuffer objects.
	///
	/// ## Declaration
	/// ```c
	/// #include <zircon/syscalls-next.h>
	///
	/// zx_status_t zx_iob_create_shared_region(uint64_t options,
	/// uint64_t size,
	/// zx_handle_t* out);
	/// ```
	///
	/// ## Description
	///
	/// Creates a shared region that can be used with multiple IOBuffer objects.
	///
	/// `options` must be zero. `size` must be a multiple of the page size.
	///
	/// ## Return value
	///
	/// On success, `ZX_OK` is returned and `out` will be populated with a new handle.
	///
	/// ## Errors
	///
	/// `ZX_ERR_ACCESS_DENIED` The proess does not have permissions to create shared IOBuffer
	/// regions.
	///
	/// `ZX_ERR_INVALID_ARGS` `options` was nonzero (there are no non-default options supported at
	/// this time), or `size` was zero or not a multiple of the page size.
	///
	/// `ZX_ERR_NO_MEMORY` Failure due to lack of memory to allocate the shared region.
	@next
	strict CreateSharedRegion(struct {
	options uint64;
	size uint64;
	}) -> (resource struct {
	out Handle;
	}) error Status;
	};