摘要
使用一組選項建立 IOBuffer。
宣告
#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);
說明
zx_iob_create() 會建立 IOBuffer，這是一種用於點對點通訊的記憶體物件。您可以將 IOBuffer 視為共用緩衝區的抽象概念，用於支援特定容器，並透過 (可選的核心介面) 讀取和寫入作業，維持資料完整性並強制執行權限。
IOBuffer 可能會有多個區域，由 region_count 指定。每個區域都可以設定為支援不同的存取模式或由區域設定的權限。
如果為某個區域設定受控存取權，系統會在建立該區域時初始化相關聯的容器。
區域說明
區域的幾何形狀和設定是由 zx_iob_region_t 區域描述結構定義。基本結構包含所有區域類型通用的欄位。
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 會指定區域的類型，以及支援該區域的記憶體物件。有效的類型如下： - ZX_IOB_REGION_TYPE_PRIVATE：由 IOB 專屬的私人記憶體所支援的區域。
access 可指定每個端點的存取權控管修飾符。必須結合下列一或多項：
ZX_IOB_ACCESS_EP0_CAN_MAP_READ可讓端點 0 將區域對應為可讀ZX_IOB_ACCESS_EP0_CAN_MAP_WRITE，授予端點 0 將區域對應為可寫入的權限ZX_IOB_ACCESS_EP0_CAN_MEDIATED_READ，授予端點 0 執行中介讀取功能的權限ZX_IOB_ACCESS_EP0_CAN_MEDIATED_WRITE，授予端點 0 執行經過調節的寫入作業的能力ZX_IOB_ACCESS_EP1_CAN_MAP_READ可讓端點 1 將區域對應為可讀ZX_IOB_ACCESS_EP1_CAN_MAP_WRITE，授予端點 1 將區域對應為可寫的權限ZX_IOB_ACCESS_EP1_CAN_MEDIATED_READ授予端點 1 執行經過中介的讀取作業的權限ZX_IOB_ACCESS_EP1_CAN_MEDIATED_WRITE授予端點 1 執行經過調節的寫入作業的權限
size 是區域的大小 (以位元組為單位)。系統會將大小向上捨入下一個系統頁面大小邊界，如 zx_system_get_page_size() 所回報。請使用 zx_object_get_info 搭配主題 ZX_INFO_IOB_REGIONS 來判斷區域的實際大小。
discipline 會指定要用於核心中介作業的記憶體存取規則。有效的規範如下： - ZX_IOB_DISCIPLINE_TYPE_NONE：沒有核心介面操作的自由格式區域。
區域類型
ZX_IOB_REGION_TYPE_PRIVATE
指定由 IOB 專屬的私人記憶體物件所支援的區域。這個記憶體物件只能透過擁有的 IOB 作業和對應作業存取。
struct zx_iob_region_private_t {
uint32_t options;
uint32_t padding1;
uint64_t padding2[3];
};
options 必須為 0
違規類型
詳情請參閱 zx_iob_discipline_type_t。
傳回值
zx_iob_create() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負值錯誤。
錯誤
ZX_ERR_INVALID_ARGS ep_out0 或 ep_out1 是無效的指標或空值、options 是 0 以外的任何值，或是 regions 設定無效 (例如無法存取區域、無法透過地圖寫入或設定為受控存取，或是科學無效)。
ZX_ERR_NO_MEMORY 由於記憶體不足，無法分配所要求的緩衝區，因此失敗。
ZX_ERR_OUT_OF_RANGE 區域數量超出上限 (64)。