Fuchsia

IOBuffer

Name

IOBuffer - Shared memory endpoint with asymmetric access control and disciplines

Synopsis

An IOBuffer (IOB) is a peered Zircon kernel object designed for high-throughput, low-latency communication and shared memory transports between processes. It combines peered session management with multi-region encapsulation, asymmetric access control, and kernel-mediated access disciplines.

Description

An IOBuffer always operates as a pair of endpoints (Endpoint 0 and Endpoint 1). It allows two processes to communicate by sharing multiple independent memory regions (up to a maximum of 64, defined by ZX_IOB_MAX_REGIONS), each configured with specific access permissions and behavior.

Peered lifetime and signaling

Like Channels and Sockets, IOBuffer endpoints are peered.

  • The endpoints control the lifetime of the backing memory regions.
  • Reference Tracking: Active virtual memory mappings created from an endpoint count as references alongside open handles to that endpoint.
  • Peer Closure: When all references (both open handles and active virtual memory mappings) to one endpoint close, the system asserts the ZX_IOB_PEER_CLOSED signal on the opposing endpoint.

Regions: Private vs. shared

An IOBuffer can encapsulate multiple memory regions:

  • Private Regions (ZX_IOB_REGION_TYPE_PRIVATE): Backed by a private VmObject uniquely owned by the IOBuffer pair. Used for isolated, point-to-point communication.
  • Shared Regions (ZX_IOB_REGION_TYPE_SHARED) (Experimental): Points to a standalone shared_region object. Multiple independent IOBuffer pairs can reference the same shared region, enabling many-to-one patterns (for example, multiple client log writers sending data to a single reader).

Asymmetric access control

You can configure each region with different permissions for Endpoint 0 and Endpoint 1. Permissions include:

  • Direct Mapping: Allows the process to map the region into its virtual address space (VMAR) for direct read/write access.
    • ZX_IOB_ACCESS_EP0_CAN_MAP_READ / _WRITE
    • ZX_IOB_ACCESS_EP1_CAN_MAP_READ / _WRITE
  • Kernel-Mediated Access: Restricts direct mapping, requiring all access to go through kernel system calls (such as zx_iob_writev). This protects against Time-of-Check to Time-of-Use (TOCTOU) attacks.
    • ZX_IOB_ACCESS_EP0_CAN_MEDIATED_READ / _WRITE
    • ZX_IOB_ACCESS_EP1_CAN_MEDIATED_READ / _WRITE

Effective rights and handle interaction

When validating a memory operation, the kernel intersects the region's access permissions (logical AND) with the endpoint handle rights. Region-level permissions cannot override handle-level permissions.

  • Map Operation: The effective read/write rights are uRn & hRn and uWn & hWn respectively, where u represents mapping permission and h represents handle rights.
  • Mediated Operation: The effective read/write rights are kRn & hRn and kWn & hWn respectively, where k represents mediated permission and h represents handle rights.

Mediated directionality vs. absolute permissions

Unlike direct mappings, kernel-mediated access operates in a logical/directional sense rather than absolute hardware permissions. For example, a logical mediated read operation (such as retrieving data from a ring buffer) may require the kernel to write to bookkeeping structures in that same region under the hood. The kernel permits such internal bookkeeping writes for read-only mediated endpoints, because the kernel acts as the trusted mediator enforcing the logic.

Memory access disciplines

Disciplines define the structured memory layout and behavior for kernel-mediated operations within a region:

  • None (ZX_IOB_DISCIPLINE_TYPE_NONE): Free-form raw byte buffer. No kernel-mediated operations.
  • ID Allocator (ZX_IOB_DISCIPLINE_TYPE_ID_ALLOCATOR) (Experimental): A thread-safe structure mapping sized data blobs to sequentially allocated numeric IDs. Useful for string interning in tracing.
  • Mediated Write Ring Buffer (ZX_IOB_DISCIPLINE_TYPE_MEDIATED_WRITE_RING_BUFFER) (Experimental): A circular ring buffer designed for concurrent, kernel-mediated writes by multiple clients and a single userspace reader (for example, high-efficiency system logging).

Mapping via VMAR

The system maps IOBuffer regions into a VMAR via zx_vmar_map_iob. Only the following VMAR options are supported:

  • ZX_VM_SPECIFIC
  • ZX_VM_SPECIFIC_OVERWRITE
  • ZX_VM_OFFSET_IS_UPPER_LIMIT
  • ZX_VM_PERM_READ
  • ZX_VM_PERM_WRITE
  • ZX_VM_MAP_RANGE

Any other VMAR options return ZX_ERR_INVALID_ARGS.

Querying object properties and regions

IOBuffers support standard property queries via zx_object_get_info.

ZX_INFO_IOB

Returns information about the overall IOBuffer instance using zx_iob_info_t:

  • options: The options used at creation.
  • region_count: The number of memory regions encapsulated.

ZX_INFO_IOB_REGIONS

Returns information about each region as an array of zx_iob_region_info_t.

  • Access Bit Swapping: When returned, the kernel swaps the access modifier bits so that Endpoint 0 access bits reflect the rights of the endpoint handle executing the query, and Endpoint 1 access bits reflect the peer's rights. This allows endpoint-agnostic libraries to validate permissions dynamically.

ZX_INFO_PROCESS_VMOS

The kernel reports the memory objects backing private IOB regions under this topic like standard VMOs. By default, backing VMOs share the name of the parent IOBuffer.

Rights

An IOBuffer handle has the following rights by default:

  • ZX_RIGHT_TRANSFER
  • ZX_RIGHT_DUPLICATE
  • ZX_RIGHT_WAIT
  • ZX_RIGHT_INSPECT
  • ZX_RIGHT_READ
  • ZX_RIGHT_WRITE
  • ZX_RIGHT_MAP
  • ZX_RIGHT_SIGNAL
  • ZX_RIGHT_SIGNAL_PEER
  • ZX_RIGHT_GET_PROPERTY
  • ZX_RIGHT_SET_PROPERTY

Properties

IOBuffers support the following properties:

  • ZX_PROP_NAME: Used for diagnostics and attributing memory.

Signals

The system can set the following signals for an IOBuffer endpoint:

  • ZX_IOB_PEER_CLOSED: The peer endpoint closed (including all handles and active mappings).
  • ZX_IOB_SHARED_REGION_UPDATED (Experimental): Raised when a shared region has been updated by a mediated write.

Syscalls