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,
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 an abstraction over a shared buffer 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.
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 {
uint32_t type;
uint32_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_EP0_CAN_MAP_READ to grant endpoint 0 to ability to map the region as readable
- ZX_IOB_EP0_CAN_MAP_WRITE to grant endpoint 0 to ability to map the region as writable
- ZX_IOB_EP1_CAN_MAP_READ to grant endpoint 1 to ability to map the region as readable
- ZX_IOB_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
ZX_IOB_DISCIPLINE_TYPE_NONE
struct iob_discipline_t {
uint64_t type; // Must be ZX_IOB_DISCIPLINE_TYPE_NONE
};
Specifies a free form region with no kernel mediated operations.
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
ZX_ERR_NO_MEMORY Failure due to lack of memory to allocated the requested buffers.