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