blob: 112cf8440a38f395114912565bd4903cd0a38e5b [file] [log] [blame]
// Copyright 2019 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.
library zx;
@transport("Syscall")
protocol Iommu {
/// ## Summary
///
/// Create a new IOMMU object in the kernel.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_iommu_create(zx_handle_t resource,
/// uint32_t type,
/// const void* desc,
/// size_t desc_size,
/// zx_handle_t* out);
/// ```
///
/// ## Description
///
/// `zx_iommu_create()` creates a new object in the kernel representing an IOMMU device.
///
/// The value of *type* determines the interpretation of *desc*. See below for
/// details about the values of *type*.
///
/// Upon success, a handle for the new IOMMU is returned. This handle will have rights
/// **ZX_RIGHT_DUPLICATE** and **ZX_RIGHT_TRANSFER**.
///
/// ### *type* = **ZX_IOMMU_TYPE_DUMMY**
///
/// This type represents a no-op IOMMU. It provides no hardware-level protections
/// against unauthorized access to memory. It does allow pinning of physical memory
/// pages, to prevent the reuse of a page until the driver using the page says it is
/// done with it.
///
/// *desc* must be a valid pointer to a value of type `zx_iommu_desc_dummy_t`.
/// *desc_size* must be `sizeof(zx_iommu_desc_dummy_t)`.
///
/// ## Rights
///
/// *resource* must have resource kind **ZX_RSRC_KIND_ROOT**.
///
/// ## Return value
///
/// `zx_iommu_create()` returns **ZX_OK** and a handle to the new IOMMU
/// (via *out*) on success. In the event of failure, a negative error value
/// is returned.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** *resource* is not a valid handle.
///
/// **ZX_ERR_WRONG_TYPE** *resource* is not a resource handle.
///
/// **ZX_ERR_ACCESS_DENIED** *resource* handle does not have sufficient privileges.
///
/// **ZX_ERR_NOT_SUPPORTED** *type* is not a defined value or is not
/// supported on this system.
///
/// **ZX_ERR_INVALID_ARGS** *desc_size* is larger than **ZX_IOMMU_MAX_DESC_LEN**,
/// *desc* is an invalid pointer, *out* is an invalid pointer, or the contents of
/// *desc* are not valid for the given *type*.
///
/// **ZX_ERR_NO_MEMORY** Failure due to lack of memory.
/// There is no good way for userspace to handle this (unlikely) error.
/// In a future build this error will no longer occur.
///
/// ## See also
///
/// - [`zx_bti_create()`]
/// - [`zx_bti_pin()`]
/// - [`zx_pmt_unpin()`]
///
/// [`zx_bti_create()`]: bti_create.md
/// [`zx_bti_pin()`]: bti_pin.md
/// [`zx_pmt_unpin()`]: pmt_unpin.md
Create(resource struct {
resource handle:RESOURCE;
type uint32;
@voidptr
desc vector<byte>;
}) -> (resource struct {
out handle:IOMMU;
}) error status;
};