摘要
使用一組選項建立 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，將區域對應為可讀取狀態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，將區域對應為可讀取狀態ZX_IOB_ACCESS_EP1_CAN_MAP_WRITE，將區域對應為可寫入的權限授予端點 1ZX_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];
};
選項必須為 0
違規類型
詳情請參閱 zx_iob_discipline_type_t。
傳回值
zx_iob_create() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負數錯誤值。
錯誤
ZX_ERR_INVALID_ARGS ep_out0 或 ep_out1 是無效指標或 NULL，options 是 0 以外的任何值，或是區域設定無效 (例如區域無法存取，既非可寫入地圖，也未設定為中介存取，或是學科無效)。
ZX_ERR_NO_MEMORY 由於記憶體不足，無法配置所要求的緩衝區，因此發生錯誤。
ZX_ERR_OUT_OF_RANGE 區域數量超出上限 (64 個)。