zx_iob_create

Summary

Create an IOBuffer with a set of options.

Declaration

#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.

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.

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).