main/syscalls/iob_create.md

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

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_iob_create

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