API庫函式是計算機語言庫函式之一，支持以下操作：互連控制器操作、群集拓撲操作、記憶體段操作，包括段管理和數據訪問等。
基本介紹
- 中文名：API庫函式
- 學科：計算機
- 實質：語言庫函式
- 支持操作：互連控制器操作
API庫函式
API 庫函式
API 庫函式支持以下操作：
API 庫函式
API 庫函式支持以下操作：
互連控制器操作
群集拓撲操作
記憶體段操作，包括段管理和數據訪問
屏障 (barrier) 操作
事件操作
互連控制器操作
控制器操作提供了訪問控制器的機制，還可以確定底層互連的特徵。下面列出了有關控制器操作的信息：
控制器操作提供了訪問控制器的機制，還可以確定底層互連的特徵。下面列出了有關控制器操作的信息：
獲取控制器
獲取控制器屬性
釋放控制器
RSM_get_controller
int rsm_get_controller(char *name, rsmapi_controller_handle_t *controller);
int rsm_get_controller(char *name, rsmapi_controller_handle_t *controller);
rsm_get_controller 操作可獲取給定控制器實例（如 sci0 或 loopback）的控制器句柄。返回的控制器句柄用於後續 RSM 庫調用。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_CTLR_NOT_PRESENT
控制器不存在
控制器不存在
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_BAD_LIBRARY_VERSION
庫版本無效
庫版本無效
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
rsm_release_controller
int rsm_release_controller(rsmapi_controller_handle_t chdl);
int rsm_release_controller(rsmapi_controller_handle_t chdl);
此函式可用於釋放與給定控制器句柄關聯的控制器。每個 rsm_release_controller 調用都必須對應一個 rsm_get_controller。當與某個控制器關聯的所有控制器句柄都被釋放後，與此控制器關聯的系統資源將被釋放。嘗試訪問已釋放控制器句柄，或者嘗試訪問已釋放控制器句柄上的導入段或導出段都是非法操作。執行此類嘗試的結果是不確定的。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
rsm_get_controller_attr
int rsm_get_controller_attr(rsmapi_controller_handle_t chdl, rsmapi_controller_attr_t *attr);
int rsm_get_controller_attr(rsmapi_controller_handle_t chdl, rsmapi_controller_attr_t *attr);
此函式可用於獲取指定控制器句柄的屬性。以下列出了此函式當前已定義的屬性：
typedef struct {
uint_t attr_direct_access_sizes;
uint_t attr_atomic_sizes;
size_t attr_page_size;
size_t attr_max_export_segment_size;
size_t attr_tot_export_segment_size;
ulong_t attr_max_export_segments;
size_t attr_max_import_map_size;
size_t attr_tot_import_map_size;
ulong_t attr_max_import_segments;
} rsmapi_controller_attr_t;返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
群集拓撲操作
導出操作和導入操作所需的關鍵互連數據包括：
導出操作和導入操作所需的關鍵互連數據包括：
導出群集節點 ID
導入群集節點 ID
控制器名稱
作為基本約束，為段導入指定的控制器必須與用於對應的段導出的控制器具有物理連線。此接口定義互連拓撲有助於應用程式建立有效的導出和導入策略。所提供的數據包括本地節點 ID、本地控制器實例名稱以及每個本地控制器的遠程連線規範。
導出記憶體的應用程式組件可以使用此接口提供的數據來查找現有本地控制器集。此接口提供的數據還可用於正確分配控制器，以便創建和發布段。應用程式組件可以通過與硬體互連和應用程式軟體分發一致的控制器集來有效分發導出的段。
必須向要導入記憶體的應用程式組件通知記憶體導出中所用的段 ID 和控制器。通常，此信息通過預定義的段和控制器對進行傳送。導入組件可以使用拓撲數據來確定適用於段導入操作的控制器。
rsm_get_interconnect_topology
int rsm_get_interconnect_topology(rsm_topology_t **topology_data);
int rsm_get_interconnect_topology(rsm_topology_t **topology_data);
此函式返回一個指針，該指針指向應用程式指針所指定位置的拓撲數據。下面定義了拓撲數據結構。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_TOPOLOGY_PTR
拓撲指針無效
拓撲指針無效
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
rsm_free_interconnect_topology
void rsm_free_interconnect_topology(rsm_topology_t *topology_data);
void rsm_free_interconnect_topology(rsm_topology_t *topology_data);
rsm_free_interconnect_topology 操作可釋放通過 rsm_get_interconnect_topology 分配的記憶體。
返回值：無。
數據結構
從 rsm_get_topology_data 返回的指針會引用 rsm_topology_t structure。此結構為每個本地控制器提供本地節點 ID 以及指向 connections_t 結構的指針數組。
從 rsm_get_topology_data 返回的指針會引用 rsm_topology_t structure。此結構為每個本地控制器提供本地節點 ID 以及指向 connections_t 結構的指針數組。
typedef struct rsm_topology {
rsm_nodeid_t local_nodeid;
uint_t local_cntrl_count;
connections_t *connections;
} rsm_topology_t;管理操作
RSM 段 ID 可以由應用程式指定，或者由系統使用 rsm_memseg_export_publish() 函式生成。指定段 ID 的應用程式需要使用保留範圍的段 ID。要保留一組段 ID，請使用 rsm_get_segmentid_range 並在段 ID 配置檔案 /etc/rsm/rsm.segmentid 中定義保留範圍的段 ID。應用程式可以使用 rsm_get_segmentid_range 函式來獲取為應用程式保留的段 ID 範圍。此函式會讀取在 /etc/rsm/rsm.segmentid 檔案中針對給定應用程式 ID 定義的段 ID 範圍。
RSM 段 ID 可以由應用程式指定，或者由系統使用 rsm_memseg_export_publish() 函式生成。指定段 ID 的應用程式需要使用保留範圍的段 ID。要保留一組段 ID，請使用 rsm_get_segmentid_range 並在段 ID 配置檔案 /etc/rsm/rsm.segmentid 中定義保留範圍的段 ID。應用程式可以使用 rsm_get_segmentid_range 函式來獲取為應用程式保留的段 ID 範圍。此函式會讀取在 /etc/rsm/rsm.segmentid 檔案中針對給定應用程式 ID 定義的段 ID 範圍。
應用程式 ID 是指用於標識應用程式的以空字元結尾的字元串。應用程式可以使用任何等於或大於 baseid 並且小於 baseid+length 的值。如果修改了 baseid 或 length，則返回到應用程式的段 ID 可能會超出保留的範圍。要避免此問題，請使用相對於保留的一組段 ID 的偏移來獲取段 ID。
/etc/rsm/rsm.segmentid 檔案中的各項形式如下：
#keyword appid baseid length
reserve SUNWfoo 0x600000 100
這些項由可以用制表符或空格分隔的字元串組成。第一個字元串是關鍵字 reserve，後跟應用程式標識符（不包含空格的字元串）。應用程式標識符之後是 baseid，即保留範圍的起始段 ID（十六進制）。baseid 之後是 length，即保留的段 ID 數。注釋行的第一列中包含 #。此檔案不應包含空行。為系統保留的段 ID 在 /usr/include/rsm/rsm_common.h 頭檔案中定義。應用程式不能使用為系統保留的段 ID。
rsm_get_segmentid_range 函式返回 0 表示成功。如果此函式失敗，則會返回以下錯誤值之一：
RSMERR_BAD_ADDR
傳遞的地址無效
傳遞的地址無效
RSMERR_BAD_APPID
未在 /etc/rsm/rsm.segmentid 檔案中定義應用程式 ID
未在 /etc/rsm/rsm.segmentid 檔案中定義應用程式 ID
RSMERR_BAD_CONF
配置檔案 /etc/rsm/rsm.segmentid 不存在或無法讀取。檔案格式配置錯誤
配置檔案 /etc/rsm/rsm.segmentid 不存在或無法讀取。檔案格式配置錯誤
記憶體段操作
通常，RSM 段表示一組映射到連續虛擬地址範圍的非連續物理記憶體頁。通過 RSM 段導出和段導入操作，可以在互連繫統之間共享物理記憶體區域。物理頁所在節點的進程稱為記憶體的導出者。為遠程訪問發布的導出段將具有給定節點所特有的段標識符。段 ID 可以由導出者或 RSMAPI 框架指定。
通常，RSM 段表示一組映射到連續虛擬地址範圍的非連續物理記憶體頁。通過 RSM 段導出和段導入操作，可以在互連繫統之間共享物理記憶體區域。物理頁所在節點的進程稱為記憶體的導出者。為遠程訪問發布的導出段將具有給定節點所特有的段標識符。段 ID 可以由導出者或 RSMAPI 框架指定。
互連節點的進程通過創建 RSM 導入段來對導出的記憶體進行訪問。RSM 導入段與一個導出段連線，而不是與本地物理頁連線。如果互連支持記憶體映射，則導入者可以使用導入段的本地記憶體映射地址來讀寫導出的記憶體。如果互連不支持記憶體映射，則導入進程會使用記憶體訪問元語。
導出端記憶體段操作
導出記憶體段時，應用程式首先通過常規作業系統接口（如 System V 共享記憶體接口、mmap 或 valloc）來分配其虛擬地址空間中的記憶體。分配記憶體之後，應用程式將調用 RSMAPI 庫接口來創建和標記段。標記段之後，RSMAPI 庫接口將物理頁綁定到已分配的虛擬範圍。綁定物理頁之後，RSMAPI 庫接口會發布段以供導入進程訪問。
導出記憶體段時，應用程式首先通過常規作業系統接口（如 System V 共享記憶體接口、mmap 或 valloc）來分配其虛擬地址空間中的記憶體。分配記憶體之後，應用程式將調用 RSMAPI 庫接口來創建和標記段。標記段之後，RSMAPI 庫接口將物理頁綁定到已分配的虛擬範圍。綁定物理頁之後，RSMAPI 庫接口會發布段以供導入進程訪問。
--------------------------------------------------------------------------------
注 –
如果虛擬地址空間是使用 mmap 獲取的，則映射必須為 MAP_PRIVATE。
注 –
如果虛擬地址空間是使用 mmap 獲取的，則映射必須為 MAP_PRIVATE。
--------------------------------------------------------------------------------
導出端記憶體段操作包括：
創建和銷毀記憶體段
發布和取消發布記憶體段
重新綁定記憶體段的後備存儲
創建和銷毀記憶體段
使用 rsm_memseg_export_create 建立新記憶體段可以在創建時將物理記憶體與該段進行關聯。此操作將返回新記憶體段的導出端記憶體段句柄。段在創建進程的生命周期內一直存在，或者在使用 rsm_memseg_export_destroy 銷毀該段之前一直存在。
使用 rsm_memseg_export_create 建立新記憶體段可以在創建時將物理記憶體與該段進行關聯。此操作將返回新記憶體段的導出端記憶體段句柄。段在創建進程的生命周期內一直存在，或者在使用 rsm_memseg_export_destroy 銷毀該段之前一直存在。
--------------------------------------------------------------------------------
注 –
如果在導入端下線之前執行銷毀操作，則會強制下線。
注 –
如果在導入端下線之前執行銷毀操作，則會強制下線。
--------------------------------------------------------------------------------
創建段
int rsm_memseg_export_create(rsmapi_controller_handle_t controller, rsm_memseg_export_handle_t *memseg, void *vaddr, size_t size, uint_t flags);
此函式可用於創建段句柄。創建段句柄之後，段句柄會綁定到指定的虛擬地址範圍 [vaddr..vaddr+size]。此範圍必須有效並基於控制器的 alignment 屬性對齊。flags 參數是位掩碼，可用於執行以下操作：
解除綁定段
重新綁定段
將 RSM_ALLOW_REBIND 傳遞給 flags
支持鎖定操作
將 RSM_LOCK_OPS 傳遞給 flags
--------------------------------------------------------------------------------
注 –
RSMAPI 的初始發行版中不包括 RSM_LOCK_OPS 標誌。
注 –
RSMAPI 的初始發行版中不包括 RSM_LOCK_OPS 標誌。
--------------------------------------------------------------------------------
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_CTLR_NOT_PRESENT
控制器不存在
控制器不存在
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_LENGTH
長度為零或長度超出控制器限制
長度為零或長度超出控制器限制
RSMERR_BAD_ADDR
地址無效
地址無效
RSMERR_PERM_DENIED
許可權被拒絕
許可權被拒絕
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
RSMERR_BAD_MEM_ALIGNMENT
地址未在頁邊界上對齊
地址未在頁邊界上對齊
RSMERR_INTERRUPTED
操作被信號中斷
操作被信號中斷
銷毀段
int rsm_memseg_export_destroy(rsm_memseg_export_handle_t memseg);
此函式可用於解除分配段及其可用資源。將強制斷開與所有導入進程的連線。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_POLLFD_IN_USE
pollfd 正在使用
pollfd 正在使用
發布、重新發布和取消發布記憶體段
通過發布操作，其他互連節點可以導入記憶體段。一個導出段可能會在多個互連適配器上發布。
通過發布操作，其他互連節點可以導入記憶體段。一個導出段可能會在多個互連適配器上發布。
段 ID 可以在授權範圍內指定或指定為零，此時 RSMAPI 框架會生成有效的段 ID 並傳遞迴該段 ID。
段訪問控制列表由多對節點 ID 和訪問許可權組成。對於列表中指定的每個節點 ID，關聯的讀/寫許可權會通過三個八進制數字提供給屬主、組和其他用戶，這與 Solaris 檔案許可權一樣。在訪問控制列表中，每個八進制數字都可以具有以下值：
2
寫入訪問。
寫入訪問。
4
唯讀訪問。
唯讀訪問。
6
讀寫訪問。
讀寫訪問。
訪問許可權值 0624 可指定以下訪問類型：
與導出者具有相同 uid 的導入者具有讀寫訪問許可權。
與導出者具有相同 gid 的導入者僅有寫入訪問許可權。
所有其他導入者僅有讀取訪問許可權。
提供訪問控制列表之後，未包含在此列表中的節點不能導入段。但是，如果訪問列表為空，則任何節點都可導入段。所有節點的訪問許可權等同於導出進程的屬主/組/其他用戶檔案創建許可權。
--------------------------------------------------------------------------------
注 –
節點應用程式負責管理段標識符的指定，從而確保導出節點的唯一性。
注 –
節點應用程式負責管理段標識符的指定，從而確保導出節點的唯一性。
--------------------------------------------------------------------------------
發布段
int rsm_memseg_export_publish(rsm_memseg_export_handle_t memseg, rsm_memseg_id_t *segment_id, rsmapi_access_entry_t ACCESS_list[], uint_t access_list_length);
typedef struct {
rsm_node_id_t ae_node; /* remote node id allowed to access resource */
rsm_permission_t ae_permissions; /* mode of access allowed */
}rsmapi_access_entry_t;.返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_SEG_ALREADY_PUBLISHED
段已發布
段已發布
RSMERR_BAD_ACL
訪問控制列表無效
訪問控制列表無效
RSMERR_BAD_SEGID
段標識符無效
段標識符無效
RSMERR_SEGID_IN_USE
段標識符正在使用
段標識符正在使用
RSMERR_RESERVED_SEGID
段標識符已保留
段標識符已保留
RSMERR_NOT_CREATOR
不是段的創建者
不是段的創建者
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
授權的段 ID 範圍：
#define RSM_DRIVER_PRIVATE_ID_BASE
0
0
#define RSM_DRIVER_PRIVATE_ID_END
0x0FFFFF
0x0FFFFF
#define RSM_CLUSTER_TRANSPORT_ID_BASE
0x100000
0x100000
#define RSM_CLUSTER_TRANSPORT_ID_END
0x1FFFFF
0x1FFFFF
#define RSM_RSMLIB_ID_BASE
0x200000
0x200000
#define RSM_RSMLIB_ID_END
0x2FFFFF
0x2FFFFF
#define RSM_DLPI_ID_BASE
0x300000
0x300000
#define RSM_DLPI_ID_END
0x3FFFFF
0x3FFFFF
#define RSM_HPC_ID_BASE
0x400000
0x400000
#define RSM_HPC_ID_END
0x4FFFFF
0x4FFFFF
以下範圍會保留，以便在發布值為零時由系統進行分配。
#define RSM_USER_APP_ID_BASE
0x80000000
0x80000000
#define RSM_USER_APP_ID_END
0xFFFFFFF
0xFFFFFFF
重新發布段
int rsm_memseg_export_republish(rsm_memseg_export_handle_t memseg, rsmapi_access_entry_t access_list[], uint_t access_list_length);
此函式可用於建立新的節點訪問列表和段訪問模式。這些更改僅會影響將來的導入調用，並且不會撤消已準許的導入請求。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_SEG_NOT_PUBLISHED
段未發布
段未發布
RSMERR_BAD_ACL
訪問控制列表無效
訪問控制列表無效
RSMERR_NOT_CREATOR
不是段的創建者
不是段的創建者
RSMERR_INSUFFICIENT_MEMF
記憶體不足
記憶體不足
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
RSMERR_INTERRUPTED
操作被信號中斷
操作被信號中斷
取消發布段
int rsm_memseg_export_unpublish(rsm_memseg_export_handle_t memseg);
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_SEG_NOT_PUBLISHED
段未發布
段未發布
RSMERR_NOT_CREATOR
不是段的創建者
不是段的創建者
RSMERR_INTERRUPTED
操作被信號中斷
操作被信號中斷
重新綁定記憶體段
重新綁定操作可釋放導出段的當前後備存儲。釋放導出段的當前後備存儲之後，重新綁定操作將分配新的後備存儲。應用程式必須首先獲取分配給段的新虛擬記憶體。此操作對於段的導入者是透明的。
重新綁定操作可釋放導出段的當前後備存儲。釋放導出段的當前後備存儲之後，重新綁定操作將分配新的後備存儲。應用程式必須首先獲取分配給段的新虛擬記憶體。此操作對於段的導入者是透明的。
--------------------------------------------------------------------------------
注 –
應用程式負責防止在重新綁定操作完成之前對段數據進行訪問。重新綁定過程中從段中檢索數據不會導致系統故障，但執行此類操作的結果是不確定的。
注 –
應用程式負責防止在重新綁定操作完成之前對段數據進行訪問。重新綁定過程中從段中檢索數據不會導致系統故障，但執行此類操作的結果是不確定的。
--------------------------------------------------------------------------------
重新綁定段
int rsm_memseg_export_rebind(rsm_memseg_export_handle_t memseg, void *vaddr, offset_t off, size_t size);
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_LENGTH
長度無效
長度無效
RSMERR_BAD_ADDR
地址無效
地址無效
RSMERR_REBIND_NOT_ALLOWED
不允許重新綁定
不允許重新綁定
RSMERR_NOT_CREATOR
不是段的創建者
不是段的創建者
RSMERR_PERM_DENIED
許可權被拒絕
許可權被拒絕
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
RSMERR_INTERRUPTED
操作被信號中斷
操作被信號中斷
導入端記憶體段操作
以下列出了導入端操作：
以下列出了導入端操作：
連線和下線記憶體段
訪問導入的段記憶體
屏障 (barrier) 操作，用於強制設定數據訪問操作順序以及用於訪問錯誤檢測
連線操作用於創建 RSM 導入段並與導出的段形成邏輯連線。
對導入的段記憶體的訪問由以下三個接口類別提供：
段訪問。
數據傳送。
段記憶體映射。
連線和下線記憶體段
連線到段
連線到段
int rsm_memseg_import_connect(rsmapi_controller_handle_t controller, rsm_node_id_t node_id, rsm_memseg_id_t segment_id, rsm_permission_t perm, rsm_memseg_import_handle_t *im_memseg);
此函式可用於通過指定的許可權 perm 連線到遠程節點 node_id 上的段 segment_id。連線到段之後，此函式會返回一個段句柄。
參數 perm 用於指定導入者針對此連線請求的訪問模式。要建立連線，可將導出者指定的訪問許可權與導入者使用的訪問模式、用戶 ID 和組 ID 進行比較。如果請求模式無效，則會拒絕連線請求。perm 參數限制為以下八進制值：
0400
讀取模式
讀取模式
0200
寫入模式
寫入模式
0600
讀/寫模式
讀/寫模式
指定的控制器必須與用於段導出的控制器具有物理連線。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_CTLR_NOT_PRESENT
控制器不存在
控制器不存在
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_PERM_DENIED
許可權被拒絕
許可權被拒絕
RSMERR_SEG_NOT_PUBLISHED_TO_NODE
未將段發布到節點
未將段發布到節點
RSMERR_SEG_NOT_PUBLISHED
未發布此類段
未發布此類段
RSMERR_REMOTE_NODE_UNREACHABLE
無法訪問遠程節點
無法訪問遠程節點
RSMERR_INTERRUPTED
連線已中斷
連線已中斷
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
斷開段連線
int rsm_memseg_import_disconnect(rsm_memseg_import_handle_t im_memseg);
此函式可用於斷開段連線。斷開段連線之後，此函式將釋放段的資源。所有與下線的段的現有映射都將刪除。句柄 im_memseg 將會釋放。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_SEG_STILL_MAPPED
仍映射段
仍映射段
RSMERR_POLLFD_IN_USE
pollfd 正在使用
pollfd 正在使用
記憶體訪問元語
以下接口提供了一種機制，用於在 8 位和 64 位數據之間進行傳送。get 接口使用重複計數 (rep_cnt) 來表示進程將從連續位置讀取的給定大小的數據項數。這些位置從導入的段中的位元組偏移 offset 開始。數據會寫入從 datap 開始的連續位置。put 接口可使用重複計數 (rep_cnt)。此計數表示進程將從連續位置讀取的數據項數。這些位置從 datap 開始。然後，數據會寫入已導入段中的連續位置。這些位置從 offset 參數所指定的位元組偏移開始。
以下接口提供了一種機制，用於在 8 位和 64 位數據之間進行傳送。get 接口使用重複計數 (rep_cnt) 來表示進程將從連續位置讀取的給定大小的數據項數。這些位置從導入的段中的位元組偏移 offset 開始。數據會寫入從 datap 開始的連續位置。put 接口可使用重複計數 (rep_cnt)。此計數表示進程將從連續位置讀取的數據項數。這些位置從 datap 開始。然後，數據會寫入已導入段中的連續位置。這些位置從 offset 參數所指定的位元組偏移開始。
如果源與目標具有不兼容的位元組存儲順序特徵，則這些接口還可提供位元組交換功能。
函式原型：
int rsm_memseg_import_get8(rsm_memseg_import_handle_t im_memseg, off_t offset, uint8_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get16(rsm_memseg_import_handle_t im_memseg, off_t offset, uint16_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get32(rsm_memseg_import_handle_t im_memseg, off_t offset, uint32_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get64(rsm_memseg_import_handle_t im_memseg, off_t offset, uint64_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put8(rsm_memseg_import_handle_t im_memseg, off_t offset, uint8_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put16(rsm_memseg_import_handle_t im_memseg, off_t offset, uint16_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put32(rsm_memseg_import_handle_t im_memseg, off_t offset, uint32_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put64(rsm_memseg_import_handle_t im_memseg, off_t offset, uint64_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get16(rsm_memseg_import_handle_t im_memseg, off_t offset, uint16_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get32(rsm_memseg_import_handle_t im_memseg, off_t offset, uint32_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_get64(rsm_memseg_import_handle_t im_memseg, off_t offset, uint64_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put8(rsm_memseg_import_handle_t im_memseg, off_t offset, uint8_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put16(rsm_memseg_import_handle_t im_memseg, off_t offset, uint16_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put32(rsm_memseg_import_handle_t im_memseg, off_t offset, uint32_t *datap, ulong_t rep_cnt);
int rsm_memseg_import_put64(rsm_memseg_import_handle_t im_memseg, off_t offset, uint64_t *datap, ulong_t rep_cnt);
以下接口用於進行規模大於段訪問操作所支持範圍的數據傳送。
放置段
int rsm_memseg_import_put(rsm_memseg_import_handle_t im_memseg, off_t offset, void *src_addr, size_t length);
此函式可用於將數據從 src_addr 和 length 所指定的本地記憶體複製到句柄和偏移所指定的對應導入的段所在位置。
獲取段
int rsm_memseg_import_get(rsm_memseg_import_handle_t im_memseg, off_t offset, void *dst_addr, size_t length);
此函式類似於 rsm_memseg_import_put()，但是數據從導入的段流入 dest_vec 參數所定義的本地區域。
put 和 get 例程從參數 offset 所指定的位元組偏移位置寫入或讀取指定的數據量。這些例程從段的基地址開始。偏移必須在相應的邊界對齊。例如，rsm_memseg_import_get64() 要求 offset 和 datap 在雙字界對齊，而 rsm_memseg_import_put32() 則要求偏移在單字邊界對齊。
預設情況下，段的屏障 (barrier) 模式屬性為 implicit。 隱式屏障 (barrier) 模式表示調用方假設數據傳送在從操作返回時已完成或失敗。 由於預設屏障 (barrier) 模式為隱式，因此應用程式必須初始化屏障 (barrier)。使用預設模式時，應用程式會在調用 put 或 get 例程之前使用 rsm_memseg_import_init_barrier() 函式初始化屏障 (barrier)。要使用顯式操作模式，調用方必須使用屏障 (barrier) 操作來強制完成傳送。強制完成傳送之後，調用方必須確定強制完成是否產生了任何錯誤。
--------------------------------------------------------------------------------
注 –
通過在 rsm_memseg_import_map() 例程中傳遞偏移可以部分映射導入段。如果部分映射了導入段，則 put 或 get 例程中的 offset 參數是相對於段的基地址。用戶必須確保將正確的位元組偏移傳遞給 put 和 get 例程。
注 –
通過在 rsm_memseg_import_map() 例程中傳遞偏移可以部分映射導入段。如果部分映射了導入段，則 put 或 get 例程中的 offset 參數是相對於段的基地址。用戶必須確保將正確的位元組偏移傳遞給 put 和 get 例程。
--------------------------------------------------------------------------------
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
RSMERR_BAD_MEM_ALIGNMENT
記憶體對齊無效
記憶體對齊無效
RSMERR_BAD_OFFSET
偏移無效
偏移無效
RSMERR_BAD_LENGTH
長度無效
長度無效
RSMERR_PERM_DENIED
許可權被拒絕
許可權被拒絕
RSMERR_BARRIER_UNINITIALIZED
未初始化屏障 (barrier)
未初始化屏障 (barrier)
RSMERR_BARRIER_FAILURE
I/O 完成錯誤
I/O 完成錯誤
RSMERR_CONN_ABORTED
連線異常中止
連線異常中止
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
分散/集中訪問
rsm_memseg_import_putv() 和 rsm_memseg_import_getv() 函式允許使用 I/O 請求列表來替代單個源地址和單個目標地址。
rsm_memseg_import_putv() 和 rsm_memseg_import_getv() 函式允許使用 I/O 請求列表來替代單個源地址和單個目標地址。
函式原型：
int rsm_memseg_import_putv(rsm_scat_gath_t *sg_io);
int rsm_memseg_import_getv(rsm_scat_gath_t *sg_io);
int rsm_memseg_import_getv(rsm_scat_gath_t *sg_io);
使用分散/集中列表的 I/O 向量部分 (sg_io) 可以指定本地虛擬地址或 local_memory_handles。句柄是一種重複使用本地地址範圍的有效方法。在釋放句柄之前，已分配的系統資源（如已鎖定的本地記憶體）會一直保留。句柄的支持函式包括 rsm_create_localmemory_handle() 和 rsm_free_localmemory_handle()。
可以將虛擬地址或句柄收集到向量中，以便寫入單個遠程段。另外，還可以將從單個遠程段讀取的結果分散到虛擬地址或句柄的向量中。
整個向量的 I/O 會在返回之前啟動。導入段的屏障 (barrier) 模式屬性可確定 I/O 是否在函式返回之前已完成。將屏障 (barrier) 模式屬性設定為 implicit 可保證數據傳送按照在向量中的輸入順序完成。在每個列表項開始時會執行隱式屏障 (barrier) 打開，在每個列表項結束時會執行隱式屏障 (barrier) 關閉。如果檢測到錯誤，向量的 I/O 會終止並且函式會立即返回。剩餘計數表示其 I/O 尚未完成或尚未啟動的項數。
可以指定在 putv 或 getv 操作成功時，向目標段傳送通知事件。要指定傳送通知事件，請在 rsm_scat_gath_t 結構的 flags 項中指定 RSM_IMPLICIT_SIGPOST 值。flags 項還可以包含值 RSM_SIGPOST_NO_ACCUMULATE，該值在設定了 RSM_IMPLICIT_SIGPOST 的情況下會傳遞給信號傳遞操作。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SGIO
分散/集中結構指針無效
分散/集中結構指針無效
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_BAD_ADDR
地址錯誤
地址錯誤
RSMERR_BAD_OFFSET
偏移無效
偏移無效
RSMERR_BAD_LENGTH
長度無效
長度無效
RSMERR_PERM_DENIED
許可權被拒絕
許可權被拒絕
RSMERR_BARRIER_FAILURE
I/O 完成錯誤
I/O 完成錯誤
RSMERR_CONN_ABORTED
連線異常中止
連線異常中止
RSMERR_INSUFFICIENT_RESOURCES
資源不足
資源不足
RSMERR_INTERRUPTED
操作被信號中斷
操作被信號中斷
獲取本地句柄
int rsm_create_localmemory_handle(rsmapi_controller_handle_t cntrl_handle, rsm_localmemory_handle_t *local_handle, caddr_t local_vaddr, size_t length);
此函式可用於獲取本地句柄，以便在後續調用 putv 或 getv 時用於 I/O 向量。儘快釋放句柄可節省系統資源（特別是本地句柄占用的記憶體），這些資源可能會鎖定。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_BAD_LOCALMEM_HNDL
本地記憶體句柄無效
本地記憶體句柄無效
RSMERR_BAD_LENGTH
長度無效
長度無效
RSMERR_BAD_ADDR
地址無效
地址無效
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
釋放本地句柄
rsm_free_localmemory_handle(rsmapi_controller_handle_t cntrl_handle, rsm_localmemory_handle_t handle);
此函式可用於釋放與本地句柄關聯的系統資源。由於進程退出時會釋放屬於該進程的所有句柄，因此調用此函式可節省系統資源。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_CTLR_HNDL
控制器句柄無效
控制器句柄無效
RSMERR_BAD_LOCALMEM_HNDL
本地記憶體句柄無效
本地記憶體句柄無效
以下示例說明了主數據結構的定義。
--------------------------------------------------------------------------------
示例 2–1 主數據結構
typedef void *rsm_localmemory_handle_t
typedef struct {
ulong_tio_request_count;number of rsm_iovec_t entries
ulong_tio_residual_count;rsm_iovec_t entries not completed
inflags;
rsm_memseg_import_handle_tremote_handle; opaque handle for
import segment
rsm_iovec_t*iovec; pointer to
array of io_vec_t
} rsm_scat_gath_t;
typedef struct {
intio_type;HANDLE or VA_IMMEDIATE
union {
rsm_localmemory_handle_thandle;used with HANDLE
caddr_tvirtual_addr;used with
VA_IMMEDIATE
} local;
size_t local_offset; offset from handle base vaddr
size_t import_segment_offset; offset from segment base vaddr
size_t transfer_length;
} rsm_iovec_t;
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
段映射
映射操作只能用於本機體系結構互連，如 Dolphin-SCI 或 NewLink。映射段可授予 CPU 記憶體操作訪問該段的許可權，從而節省了調用記憶體訪問元語的開銷。
映射操作只能用於本機體系結構互連，如 Dolphin-SCI 或 NewLink。映射段可授予 CPU 記憶體操作訪問該段的許可權，從而節省了調用記憶體訪問元語的開銷。
導入段映射
int rsm_memseg_import_map(rsm_memseg_import_handle_t im_memseg, void **address, rsm_attribute_t attr, rsm_permission_t perm, off_t offset, size_t length);
此函式可用於將導入的段映射成調用方地址空間。如果指定了屬性 RSM_MAP_FIXED，則此函式會在 **address 中指定的值所在位置映射段。
typedef enum {
RSM_MAP_NONE = 0x0, /* system will choose available virtual address */
RSM_MAP_FIXED = 0x1, /* map segment at specified virtual address */
} rsm_map_attr_t;返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_ADDR
地址無效
地址無效
RSMERR_BAD_LENGTH
長度無效
長度無效
RSMERR_BAD_OFFSET
偏移無效
偏移無效
RSMERR_BAD_PERMS
許可權無效
許可權無效
RSMERR_SEG_ALREADY_MAPPED
已映射段
已映射段
RSMERR_SEG_NOT_CONNECTED
未連線段
未連線段
RSMERR_CONN_ABORTED
連線異常中止
連線異常中止
RSMERR_MAP_FAILED
映射時出現錯誤
映射時出現錯誤
RSMERR_BAD_MEM_ALIGNMENT
地址未在頁邊界上對齊
地址未在頁邊界上對齊
取消映射段
int rsm_memseg_import_unmap(rsm_memseg_import_handle_t im_memseg);
此函式可用於從用戶虛擬地址空間中取消映射導入的段。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
屏障 (barrier) 操作
使用屏障 (barrier) 操作可以解決寫入訪問順序記憶體模型問題。屏障 (barrier) 操作還可提供遠程記憶體訪問錯誤檢測功能。
使用屏障 (barrier) 操作可以解決寫入訪問順序記憶體模型問題。屏障 (barrier) 操作還可提供遠程記憶體訪問錯誤檢測功能。
屏障 (barrier) 機制由以下操作組成：
初始化
打開
關閉
排序
打開和關閉操作定義了錯誤檢測和排序的時間間隔。通過初始化操作，可以為每個導入的段創建屏障 (barrier) 並指定屏障 (barrier) 類型。當前支持的唯一屏障 (barrier) 類型針對每個段具有一個時間間隔範圍。請使用類型參數值 RSM_BAR_DEFAULT。
成功執行關閉操作可保證成功完成所涉及的訪問操作，這些操作在屏障 (barrier) 打開操作和屏障 (barrier) 關閉操作之間進行。在屏障 (barrier) 打開操作之後直到屏障 (barrier) 關閉操作之前，不會報告單個數據訪問操作（讀取和寫入）故障。
要在屏障 (barrier) 範圍內強制設定特定的寫入完成順序，請使用顯式屏障 (barrier) 排序操作。在屏障 (barrier) 排序操作之前發出的寫入操作會先於在屏障 (barrier) 排序操作之後發出的操作完成。給定屏障 (barrier) 範圍內的寫入操作會根據其他屏障 (barrier) 範圍進行排序。
初始化屏障 (barrier)
int rsm_memseg_import_init_barrier(rsm_memseg_import_handle_t im_memseg, rsm_barrier_type_t type, rsmapi_barrier_t *barrier);
--------------------------------------------------------------------------------
注 –
目前，RSM_BAR_DEFAULT 是唯一支持的類型。
注 –
目前，RSM_BAR_DEFAULT 是唯一支持的類型。
--------------------------------------------------------------------------------
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_BARRIER_PTR
屏障 (barrier) 指針無效
屏障 (barrier) 指針無效
RSMERR_INSUFFICIENT_MEM
記憶體不足
記憶體不足
打開屏障 (barrier)
int rsm_memseg_import_open_barrier(rsmapi_barrier_t *barrier);
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_BARRIER_PTR
屏障 (barrier) 指針無效
屏障 (barrier) 指針無效
關閉屏障 (barrier)
int rsm_memseg_import_close_barrier(rsmapi_barrier_t *barrier);
此函式可用於關閉屏障 (barrier) 並刷新所有存儲緩衝區。此調用假設如果調用 rsm_memseg_import_close_barrier() 失敗，則調用進程將重試自上次 rsm_memseg_import_open_barrier 調用以來的所有遠程記憶體操作。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_BARRIER_PTR
屏障 (barrier) 指針無效
屏障 (barrier) 指針無效
RSMERR_BARRIER_UNINITIALIZED
未初始化屏障 (barrier)
未初始化屏障 (barrier)
RSMERR_BARRIER_NOT_OPENED
未打開屏障 (barrier)
未打開屏障 (barrier)
RSMERR_BARRIER_FAILURE
記憶體訪問錯誤
記憶體訪問錯誤
RSMERR_CONN_ABORTED
連線異常中止
連線異常中止
排序屏障 (barrier)
int rsm_memseg_import_order_barrier(rsmapi_barrier_t *barrier);
此函式可用於刷新所有存儲緩衝區。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_BARRIER_PTR
屏障 (barrier) 指針無效
屏障 (barrier) 指針無效
RSMERR_BARRIER_UNINITIALIZED
未初始化屏障 (barrier)
未初始化屏障 (barrier)
RSMERR_BARRIER_NOT_OPENED
未打開屏障 (barrier)
未打開屏障 (barrier)
RSMERR_BARRIER_FAILURE
記憶體訪問錯誤
記憶體訪問錯誤
RSMERR_CONN_ABORTED
連線異常中止
連線異常中止
銷毀屏障 (barrier)
int rsm_memseg_import_destroy_barrier(rsmapi_barrier_t *barrier);
此函式可用於取消分配所有屏障 (barrier) 資源。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_BAD_BARRIER_PTR
屏障 (barrier) 指針無效
屏障 (barrier) 指針無效
設定模式
int rsm_memseg_import_set_mode(rsm_memseg_import_handle_t im_memseg, rsm_barrier_mode_t mode);
此函式支持可用於 put 例程的可選顯式屏障 (barrier) 範圍。兩種有效的屏障 (barrier) 模式為 RSM_BARRIER_MODE_EXPLICIT 和 RSM_BARRIER_MODE_IMPLICIT。屏障 (barrier) 模式的預設值為 RSM_BARRIER_MODE_IMPLICIT。在隱式模式下，隱式屏障 (barrier) 打開和屏障 (barrier) 關閉會套用於每個 put 操作。將屏障 (barrier) 模式值設定為 RSM_BARRIER_MODE_EXPLICIT 之前，請使用 rsm_memseg_import_init_barrier 例程針對導入的段 im_memseg 初始化屏障 (barrier)。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
獲取模式
int rsm_memseg_import_get_mode(rsm_memseg_import_handle_t im_memseg, rsm_barrier_mode_t *mode);
此函式可用於獲取 put 例程中屏障 (barrier) 範圍設定的當前模式值。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效。
段句柄無效。
事件操作
通過事件操作，可以針對記憶體訪問事件實現進程同步。如果進程無法使用 rsm_intr_signal_wait() 函式，則可以多路復用事件等待，方法是通過 rsm_memseg_get_pollfd() 獲取輪詢描述符並使用 poll 系統調用。
通過事件操作，可以針對記憶體訪問事件實現進程同步。如果進程無法使用 rsm_intr_signal_wait() 函式，則可以多路復用事件等待，方法是通過 rsm_memseg_get_pollfd() 獲取輪詢描述符並使用 poll 系統調用。
--------------------------------------------------------------------------------
注 –
使用 rsm_intr_signal_post() 和 rsm_intr_signal_wait() 操作時需要處理對核心的 ioctl 調用。
注 –
使用 rsm_intr_signal_post() 和 rsm_intr_signal_wait() 操作時需要處理對核心的 ioctl 調用。
--------------------------------------------------------------------------------
傳遞信號
int rsm_intr_signal_post(void *memseg, uint_t flags);
void 指針 *memseg 可以將類型轉換為導入段句柄或導出段句柄。如果 *memseg 引用導入句柄，則此函式會嚮導出進程傳送信號。如果 *memseg 引用導出句柄，則此函式會向該段的所有導入者傳送信號。如果已針對目標段暫掛此事件，則將 flags 參數設定為 RSM_SIGPOST_NO_ACCUMULATE 可廢棄此事件。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_REMOTE_NODE_UNREACHABLE
無法訪問遠程節點
無法訪問遠程節點
等待信號
int rsm_intr_signal_wait(void * memseg, int timeout);
void 指針 *memseg 可以將類型轉換為導入段句柄或導出段句柄。進程的阻塞時間最多可達到 timeout 毫秒，或在事件發生之前一直阻塞。如果值為 -1，則進程在事件發生之前或中斷之前會一直阻塞。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
RSMERR_TIMEOUT
計時器已到期
計時器已到期
RSMERR_INTERRUPTED
等待已中斷
等待已中斷
獲取 pollfd
int rsm_memseg_get_pollfd(void *memseg, struct pollfd *pollfd);
此函式可用於通過指定段的描述符以及 rsm_intr_signal_post() 所生成的單個固定事件初始化指定的 pollfd 結構。將 pollfd 結構用於 poll 系統調用可等待 rsm_intr_signal_post 所通知的事件。如果當前未發布記憶體段，則 poll 系統調用無法返回有效的 pollfd。每次成功調用都會遞增指定段的 pollfd 引用計數。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
釋放 pollfd
int rsm_memseg_release_pollfd(oid *memseg);
此調用可遞減指定段的 pollfd 引用計數。如果引用計數為非零值，則取消發布、銷毀或取消映射段的操作會失敗。
返回值：如果成功，則返回 0。否則返回錯誤值。
RSMERR_BAD_SEG_HNDL
段句柄無效
段句柄無效
