OPNET核心函數

OPNET Modeler 核心函數
1. 核心函數簡介 1.1 命名規則 OPNET 中的核心函數具有非常標準的命名規則，以增強函數在 C/C++代碼中的可視性， 避免名稱與非 OPNET 函或變量衝突。以下列出了一些簡單的命名規則： ? ? 名稱均採用 op_作爲前綴，以標識其爲 OPNET 仿真內核提供的核心函數。 函數名的第二部分爲函數集名，用小寫字母表示，通常是函數所處理對象的名稱縮寫， 如 pk、ici、stat 等。 ? 函數名的第三部分是 子函數集名，對核心函數進一步進行了分類，如核心函數 op_pk_nfd_set()中的 nfd。 ? 核心函數主要用於對對象的操作。在函數名中，對象總是出現在動作之前，比如名稱 中的 attr_set 和 subq_flush 就將對象（attribute 和 subqueue）放在動作（set 和 flush）之 前。

1.2 參數類型 大部分核心函數的參數和返回值都 是標準的 C/C++數據類型，如 int、double、char*。除 此之外，在仿真數據結構中還通過 C/C++的 typedef 語句定義了許多參數和返回值作爲特殊的 OPNET 數據類型。儘管用戶通過核心函數來操作 OPNET 數據類型，可能對每個數據類型的基 本內容都越來越熟悉，但用戶並不需要關心數據類型確切的內部結構，因爲 OPNET 仿真數據 結構的內容因軟件版本的不同而有所改變。表 1-1 列舉了部分特殊的數據類型。 表 1-1 OPNET 中部分特殊數據類型 基本數據類型 Anvid (viewer ID) Anmid (macro ID) Andid (drawing ID) Boolean Compcode Distribution Evhandle Stathandle Ici List Anvid vid; Anmid mid; Andid did; Boolean bool; Compcode comp_status; Distribution* dist_ptr; Evhandle evh; Stathandle Stat_handle; Ici* ici_ptr; List* list_ptr; 聲明示例

Objid Packet Pmohandle Log_Handle Procedure Prohandle Sbhandle

Objid objid; Packet* pkptr; Pmohandle pmh; Log_Handle config_log_hndl; Procedure proc; Prohandle proh; Sbhandle sbh;

1. Animation Entity 動畫集由操作中特定動畫實體的 ID 號表示。之所以採用 ID 號來代替中的指針，是因爲對 於動畫觀察函數 op_vuanim， 號通信超過了了仿真範圍。 ID 儘管 ID 號只是存儲在規則的 C/C++ 整型變量中的簡單整數值，但 OPNET 也聲明瞭特定的數據類型來準確標記 ID 參數和變量。三 種基於 ID 號的動畫實體包括瀏覽器（Viewer） 、宏（Macro）和圖畫（Drawing） 。 2. Boolean 核心函數通過返回布爾值來表示結果是否正確。布爾值可與符號常量 OPC_TRUE 和 OPC_FALSE 進行比較。 3. Compcode 核心函數通過返回 Compcode 值來表示操作是否正確完成。Compcode 的值可與符號常量 OPC_COMPCOED_SUCCESS 和 OPC_COMPCOED_FAILURE 進行比較。 4. Distribution Distribution 是一種與概率密度函數（PDF）一致的數據結構，它描述了隨機數到特定數字 輸出的映射。Distribution 包含一張對映射進行編碼的數字表，指出完成該映射的算法。對於基 於表格的 Distribution，數據從 PDF 編輯器的 PDF 模型文件中讀入。這些結構均由 Dist 函數集 中核心函數操作。 5. Event Handle 事件句柄是惟一一種確定未決仿真事件（中斷）的數據結構。該結構主要在 Intrpt 核心函 數集中使用，因此可通過它們處理預設的中斷。注意，事件句柄是一種數據結構，而不是整型 或指針。因此不能把它存儲在整型或指針變量中。 6. Statistic Handle 統計量句柄是一種確定動態產生的全局和局部統計量的數據結構。統計量句柄的數據類型 爲 Stathandle， 獲得盲文句柄的惟一方法是通過核心函數的 Stat 函數集來註冊統計量。註冊統計 量時將爲其指定一個惟一的名稱，並和時間一起存儲在一個輸出矢量中。局部統計量用在特定 處理器或隊列中；全局統計量由仿真模型中的實體共享，每個實體分佈式地作用於輸出矢量。

7. ICI ICI（Interface Control Information，接口控制信息）是與仿真中斷相關的結構化數據的集合 用於進程間通信機制，傳輸分層協議接口的控制信息。ICI 由 Ici 函數集中的杧函數操作。 8. List List 是存儲在雙向鏈表中的數據元素的集合。List 中的元素可按照從簡單的 C/C++數據類 型在複雜的數據結構進行排列。List 學用於臨時存儲數據結構組，可包含各種不同類型的元素， 但通常並不這樣使用。對 List 的大小沒有限制，可在其任意位置插入或移除元素。List 由 Prg 函數集的 List 子函數集操作。 9. Object ID 對像 ID 惟一地確定了一個仿真對象。 通過使用 Objid 數據類型聲明該標識符， Id、Ima、 供 Topo 和 Pk 函數集使用。 10. Packet Packet 是數據封裝和傳輸建模中的基本仿真實體。它由 Pk 函數集中的核心函數操作。 11. Memory Object Type 某些建模需要爲其動態分配內存來存儲各種信息。每個相同大小數據組成的集合記爲一個 池，內核爲每個池分配大量的數據條目以提高標準內存分配器的效率。每個匯聚池中的內存對 象必須通過調用核心函數 op_prg_pmo_define()來創建，該函數將返回一個匯聚內存對象句柄來 標識池，用 Pmohandle 表示。創建匯聚內存對象時都爲其分配了一個惟一的名稱，仿真模型中 的實體可以共享匯聚內存對象。 12. Log Handle 當在仿真調試或數據分析中創建仿真日誌時，日誌句柄對於每個日誌項非常必要。 13. Procedure 某些核心函數將 C/C++函數指針作爲參數，但並不聲明這些參數作爲指向返回整型值的函 數的指針，而是定義了一種特殊的數據類型——Procedure。 14. Process Handle 進程句柄是惟一一種標識仿真中活動進程的數據結構，由 Pro 函數集中的核心函數使用。 需注意進程免柄是數據結構，而不是整形或指針，因而不能將它們存儲在整型或指針變量中。 15. Sar Buffer Handle Sar 緩衝句柄是惟一一種標識 Sar（Segmentation & Reassembly，分段與重組）緩衝區的數 據結構。Sar 緩衝區緩存包序列，並可對包進行分段和重裝。Sar 緩衝區由 Sar 函數集中的核心 函數創建，該函數返回訪問新緩衝區的 Sar 緩衝句柄。Sar 函數集函數利用 Sar 緩衝名柄來處理 被標識的 Sar 緩衝區。與其他 OPNET 數據結構一樣，不能將 Sar 緩衝句柄分配到整型或指針變 量中。

16. Vartype 除標準的 C/C++數據類型和特殊的仿真內核數據類型外，OPNET 還提供了另外一種數據 類型——Vartype。Vartype 數據類型可用在變量聲明或類型轉換語句中，它是 OPNET 文檔中的 特殊關鍵詞，表示函數參數可以是多種可能的數據類型之一。類型參數的傳遞由 C 描述的調用 函數確定，Vartype 用於確定哪個函數參數可用來傳遞多種數據類型。但需要注意的是，Vartype 並不像 C 中的 varargs 那樣可傳遞多種參數，每個 Vartype 參數一次只能接受一個傳遞值。 Vartype 類型的參數，可接受 int、double 或指向數據結構的指針。Vartype*是 Vartype 的一 種變體，它可接受指向變量類型的指針。Vartype*類型的參數可接受的值包括：指向整型的指 針、指向 double 的指針、指向數據結構的指針，或參數用於返回 filled-in 值時指向數據結構指 針的指針。 每個核心函數中都描述了可被 Vartype 或 Vartype*參數接受的類型值。具有該類型參數的 部分核心函數如表 1-2 所示。 表 1-2 帶 Vartype 參數的核心函數 核心函數 op_ima_obj_attr_set() op_ima_obj_attr_get() op_pk_fd_set() op_pk_fd_get() op_pk_nfd_set() op_pk_nfd_get() op_ini_attr_set() op_ini_attr_get() op_prg_list_insert() op_prg_mem_copy() op_prg_mem_free() Vartype Vartype* (fill-in) Vartype Vartype* (fill-in) Vartype Vartype* (fill-in) Vartype Vartype* (fill-in) Vartype* Vartype* Vartype* 變量類型參數

返回變量類型參數的部分核心函數如表 1-3 所示。 表 1-3 核心函數 op_prg_list_access() op_prg_list_remove() op_prg_mem_alloc() Vartype* Vartype* Vartype* 返回變量類型參數的核心函數 變量類型參數

表 1-4 accept() access() audit() bind() clear() clock() close() connect() exit() index() kill() link() listen() open() pipe() poll() read() select()

易衝突的函數名 send() signal() socket() stat() tell() truncate() unlink() wait()

1.3 多線程安全 無線模塊允許 OPNET 採用多處理器進行收/發信機管道計算。爲確保並行傳輸的正確性和 儘可能快速，五個管道階段必須採用多線程安全核心函數。核心函數定義了三個多線程安全級 別，分別是 MT-safe、MT-unsafe 和 Forced serialization。 （1）MT-safe：該類核心函數已手動進行重編碼以支持多線程。多個線程可安全地並行執 行該類核心函數。 （2）MT-unsafe：在該安全級別下，若在覈心函數中採用並行處理，將導致性能的下降， 達不到預期的結果。使用 MT-unsafe 核心函數時，應當執行適當的代碼序列化（Serialization） 。 （3）Forced serialization：對於所有已手動重編碼以支持多線程的核心函數，仿真內核採 用內部互斥來執行嚴格的序列化。最終每個核心函數將進行手動重編碼來支持多線程，它們的 狀態也將由 Forced serialization 變爲 MT-safe。

2. 基本核心函數 OPNET Modeler10.0 提供了 21 個核心函數集， 只有熟悉核心函數才能在建模時方便地進行 代碼編寫。本節按照不同的功能對常用的核心函數作了詳細的介紹。 2.1 內部模型訪問函數集 Ima（Internal Model Access，內部模型訪問）函數集是一系列提供對仿真實體動態訪問的 核心函數的集合，其中仿真實體包括仿真屬性、對象屬性、對象命令（Object Command）和進 程狀態變量。 1. op_ima_obj_attr_get (objid,attr_name,value_ptr) 此核心函數的作用是獲取給定對象的某屬性值，其參數說明如表 2-1 所示。

表 2-1 op_ima_obj_attr_get()函數的參數說明 參 數 objid attr_name 類 型 Objid const char* 給定對象的對象 ID 屬性名（必須是給定對象中已定義的，否則將出錯） 指向存儲屬性值變量的指針（Vartype* 可接受字符串或指向 整型 、double 以及複合屬性對象 ID 指針。當爲字符串時， 字符數組必須足夠大，以容納屬性值。參數指針類型必須與 給定屬性的數據類型相匹配，否則將出錯。如果屬性類型是 value_ptr Vartype* toggle ， 返 回 值 即 爲 OPC_BOOLINT_ENABLED 或 OPC_BOOLINT_DISABLED；如果屬性類型是 pofile，返回 值 即 爲 包 含 訪 問 profile 所 需 的 必 要 信 息 的 pofile specification(PrgT_Profile_Spec) 1）返回值 Compcode——如果成功獲取屬性值，即返回 OPC_COMPCODE_SUCCESS，否則返回 OPC_COMPCODE_FAILURE。 如果需要獲取給定對象的複合屬性值，則若複合屬性相等，value_ptr 的值即設爲複合屬性 中 的 一 個 對 象 ID ， 並 返 回 OPC_COMPCODE_SUCCESS ； 若 不 相 等 ， 則 返 回 OPC_COMPCODE_FAILURE。 注意：在複合屬性中，所謂的“相等” ，是指複合屬性中的所有屬性都具有相同的名稱、 類型和值，並且複合懺悔的所有子對象也相等。 2）詳解 對於網絡域對象（子網、節點和鏈路） 、節點域對象（模塊）以及預先由網絡、節點、進 程或鏈路編輯器定義的複合屬性， 都可以獲取對象屬性值。提升的屬性值可以從父對象中獲取。 要引用提升屬性，必須爲每個中間對象的屬性名附加一個點分前綴。例如，若要在節點級獲取 進程屬性，則屬性名應在包含該進程的模塊名稱之前。 並不是所有的對象屬性都可仿真中調用該函數來獲取。比如 Simulation/Access 字段被標記 爲 N/A 的屬性就不能通過調用 op_ima_obj_attr_get()來獲取。 此外，該核心函數的命令級別爲 Forced serialization。 3）目的 該函數提供了一種在仿真中動態獲取對象屬性的機制。它可用於處理器或隊列確定自身或 網絡中其他對象的屬性值。將該函數與 op_ima_obj_attr_set()結合，無需包、ICI 或中斷遞送就 可提供遠程進程間的通信。 4）錯誤 描 述

Program Abort：分段錯誤（由無效值指針、指針所指內存不足或指向無效的 attr_name 地 址所引起） 。 Recoverable Error：對象無法識別屬性名。 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象 ID 指向受限對象（由受護模型中的相關對象引起） 。 5）相關函數 採 用 op_ima_obj_attr_set() 、 op_ima_obj_attr_set_db1() 、 op_ima_obj_attr_set_int32() 和 op_ima_obj_attr_set_str()設置對象屬性值。 採 用 op_ima_sim_attr_get() 、 op_ima_sim_attr_get_db1() 、 op_ima_sim_attr_get_int32() 和 op_ima_sim_attr_get_str()獲取仿真屬性值。 採用 op_ima_obj_svar_get()獲取進程狀態變量值。 採用 op_ima_obj_command()向對象發出一個命令。 採用 op_id_self()獲取所屬處理器或隊列的對象 ID。 採用 op_id_from_name()獲取對象的對象 ID。

2. op_ima_obj_attr_set (objid,attr_name,value_ptr) 此核心函數的作用是設置給定對象的某屬性值，其參數說明如表 2-2 所示。 表 2-2 op_ima_obj_attr_set()函數的參數說明 參 數 objid attr_name value_ptr 1）返回值 Compcode——如果成功獲取屬性值，即返回 OPC_COMPCODE_SUCCESS，否則返回 OPC_COMPCODE_FAILURE。 2）詳解 對於網絡域對象（子網、節點和鏈路） 、節點域對象（模塊）以及預先由網絡、節點、進 程或鏈路編輯器定義的複合屬性，都可以設置對象屬性值。在對象中可以設置提升對象的值。 並不是所有的對象屬性都可仿真中調用該函數來設置。比如 Simulation/Access 字段被標記 爲 N/A 的屬性就不能通過調用 op_ima_obj_attr_set()來設置。 此外，該核心函數的命令級別爲 Forced serialization。 3）目的 該核心函數提供了一種在仿真過程中動態設置對象屬性的機制，可用於處理器或隊列控制 類 型 Objid const char* Vartype* 給定對象的對象 ID 屬性名 指定屬性需設置的新值 描 述

其他模塊。與函數 op_ima_obj_attr_get()結合，無需包、ICI 或中斷遞送就可提供遠程進程間的 通信。不過需要注意的是，遠端對象值的改變並不會引起中斷，只是當修改後的對象再次調用 函數 op_ima_obj_attr_get()獲取其屬性時纔會產生影響。 4）錯誤 Program Abort：分段錯誤（由無效值指針、attr_name 地址無效或值類型錯誤所引起） 。 Recoverable Error：對象無法識別屬性名。 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象屬性爲只讀。 Recoverable Error：屬性值無效。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採 用 op_ima_obj_attr_get() 、 op_ima_obj_attr_get_db1() 、 op_ima_obj_attr_get_int32() 和 op_ima_obj_attr_get_str()設置對象屬性值。 採 用 op_ima_sim_attr_get() 、 op_ima_sim_attr_get_db1() 、 op_ima_sim_attr_get_int32() 和 op_ima_sim_attr_get_str()獲取仿真屬性值。 採用 op_ima_obj_svar_get()獲取進程狀態變量值。 採用 op_ima_obj_command()向對象發出一個命令。 採用 op_id_self()獲取所屬處理器或隊列的對象 ID。 採用 op_id_from_name()獲取對象的對象 ID。

3. op_ima_sim_attr_get (attr_type, attr_name, value_ptr) 此核心函數的作用是獲取仿真屬性值，其說明如表 2-3 所示。 表 2-3 參 數 attr_type attr_name value_ptr 1）返回值 Compcode——如果成功獲取屬性值，即返回 OPC_COMPCODE_SUCCESS，否則返回 OPC_COMPCODE_FAILURE。 2）詳解 仿真屬性與子網發屬性、節點屬性、模塊屬性以及進程屬性均不同，它不在制定模塊規範 int const char* Vartype* 類 型 op_ima_sim_attr_get()函數的參數說明 描 述

屬性類型 （可以爲 OPC_IMA_INTEGER、 OPC_IMA_DOUBLE、 OPC_IMA_TOGGLE 或 OPC_IMA_STRING） 屬性名 指定存儲屬性值變量的指針

階段定義，而在仿真運行期間動態定義。仿真屬性是通過一些環境屬性機制來進行賦值的，包 括仿真命令行、環境數據庫（<HOME>/op_admin/env_db<rel>） 、shell 變量或環境文件。 該函數將觸發仿真的內部環境數據庫掃描可用值，如果無法在現有程序環境中爲仿真屬性 找到一個值，那麼它將在標準輸出設備上打印一個提示（可用仿真的 noprompt 環境屬性來取消 用戶提示） ，請求輸入一個值。一旦提示出現，就將打印一個屬性的默認值。 注意：默認值是調用核心函數時傳遞給參數的 value_ptr 值，而不使用進程模型屬性列表 中的默認初始值。因此在調用該函數時，必須事先定義 value_ptr。 如果在仿真程序環境中能夠找到給定屬性，或當提升時值時被顯示輸入，那麼認爲函數執 行成功並返回值 OPC_COMPCODE_SUCCESS。如果內核必須要引用 value_ptr 的值，則返回 OPC_COMPCODE_FAILURE。 3）目的 該核心函數提供了一種獲取在仿真運行期間設置的仿真屬性的機制。將該函數與用環境屬 性來分配仿真屬性結合起來，不僅可以獲取網絡範圍內的關鍵參數，還可獲取影響進程邏輯操 作的進程級參數。 4）錯誤 Program Abort：分段錯誤（由無效值指針、指針所指內存不足或指向畸形的 attr_name 參 數引起） 。 Program Abort：內存分配失敗。 Recoverable Error：屬性類型不可識別。 5）相關函數 採 用 op_ima_obj_attr_get() 、 op_ima_obj_attr_get_db1() 、 op_ima_obj_attr_get_int32() 和 op_ima_obj_attr_get_str()設置對象屬性值。 採 用 op_ima_sim_attr_set() 、 op_ima_sim_attr_set_db1() 、 op_ima_sim_attr_set_int32() 和 op_ima_sim_attr_set_str()設置對象屬性值。 採用 op_ima_obj_svar_get()獲取進程狀態變量值。 採用 op_ima_obj_command()向對象發出一個命令。

2.2 分佈函數集 Dist（Distribution）函數集是一系列根據特定概率分佈產生隨機值的核心函數集合。只要 具有隨機行爲的仿真都可以使用這些隨機值中的一種或幾種，如計算中斷的到達時間、產生通 信量目的地址或確定節點是否應被去激活等。

1. op_dist_load (dist_name, dist_arg0, dist_arg1) 此核心函數的作用是加載分佈以產生隨機值流，其參數說明如表 2-4 表 2-4 參 數 dist_name dist_arg0 dist_arg1 1）返回值 Distribution *——指向被加載分佈的指針。如果發生可恢復錯誤，則返回常量 OPC_NIL。 函 數 返 回 值 一 般 存 儲 在 Distribution * 類 型 的 狀 態 變 量 中 ， 稍 後 現 傳 遞 給 相 關 核 心 函 數 op_dist_outcome()。 2）詳解 分佈是根據名稱來確定的， 可以是預定義的分析分佈、 採用 PDF 編輯器建立的用戶自定義 PDF 模型或 EMA-specified PDF 模型。執行預定義的分佈可以看作是通過一兩個數值參數調用 該核心函數的參數化算法。另外兩種類型的分佈是後綴爲“.pd.s”的表格式數據文件，調用該 函數時將其加載到內存中。需要注意的是，即使預定義的分佈在 models/std/base 文件夾中有相 應的“.pd.s”文件，但這些文件都是零字節的，不包含任何分佈信息，只是讓分佈能夠顯示在 OPNET 菜單中。當加載用戶自定義的 PDF 時，將忽略參數 dist_arg0 和 dist_agr1。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數提供作爲隨機數發生器的概率分佈。該函數主要用於加載分佈，以在處理器產 生的包之間提供隨機時間間隔。任何隨機分佈的仿真參數都可以通過該函數來獲取。實際的隨 機值是通過調用函數 op_dist_outcome()來獲取的。 4）錯誤 Program Abort：分段錯誤（由無效分佈名指針引起） 。 Program Abort：內存分配失敗。 Recoverable Error：分佈名不可識別。 5）相關函數 採用 op_dist_outcome()或 op_dist_outcome_ext()獲取已加載分佈的隨機值。 採用 op_dist_uniform()獲取均勻分佈的隨機值。 採用 op_dist_unload()釋放分佈佔用的內存。 類 型 const char* double double op_dist_load()函數的參數說明 描 述

被加載的分佈名稱，通常爲字符串常量 分佈的附加參數#0 分佈的附加參數#1

2. op_dist_outcome (dist_ptr) 此核核心函數的作用是爲具有特定分佈的隨機變量產生一個浮點數， 其參數說明如表 7-5。 表 2-5 參 數 dist_ptr 1）返回值 double — — 具 有 特 定 分 布 隨 機 變 量 的 結 果 。 如 果 發 生 可 恢 復 錯 誤 ， 則 返 回 常 量 OPC_DBL_INVALID。 2）詳解 特定分佈可以是預定義的算法分佈， 也可以是之前通過函數 op_dist_load()加載的數字型表 格式分佈。該核心函數執行表格式分佈的列表查詢，並對算法分佈（如指數分佈）進行數字計 算。 該核心函數使用的隨機數流是調用 BSD random()過程產生的， 所有分佈函數集中的函數和 發生器模塊都可共享此隨機數流。隨機數流依賴於初始的種子數（seed） ，如果仿真輸入（包括 相同的隨機 seed）相同，則仿真結果可重複。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數提供了一種獲取符合某概率分佈的隨機值的機制。該函數學用於計算處理器產 生的包之間的隨機時間間隔。任何隨機分佈的仿真參數都可以通過它來獲取。 4）錯誤 Program Abort：分段錯誤（由無效分佈指針引起） 。 Recoverable Error：分佈指針爲 NIL。 5）相關函數 採用 op_dist_load()加載分佈。 採用 op_dist_uniform()獲取均勻分佈的隨機值。 採用 op_dist_unload()釋放分佈佔用的內存。 採用 op_dist_outcome_ext()獲取用戶自定義的隨機數發生器產生的隨機數。 採用 op_intrpt_schedule_self()、op_intrpt_schedule_remote()或 op_intrpt_schedule_call()分別 產生自中斷、遠程中斷和過程中斷。 類 型 Distribution* 指向被加載分佈的指針 op_dist_outcome()函數的參數說明 描 述

3. op_dist_uniform(limit) 此核心函數的作用是產生一個均勻分佈的隨機值，其參數說明如表 2-6 所示。

表 2-5 參 數 limit 1）返回值 類 型 double

op_dist_uniform()函數的參數說明 描 述

均勻分佈的取值範圍

double——產生的均勻分佈的隨機值，範圍在[0.0，limit ]中。 2）詳解 該核心函數使用的隨機數流是調用 BSD random()過程產生的， 所有分佈函數集中的函數和 發生器模塊都可共享此隨機數流。隨機數流依賴於初始的種子數（seed） ，如果仿真輸入（包括 相同的隨機 seed）相同，則仿真結果可重複。 如果參數 limit 爲負數，則返回值將是一個大於 limit 的均勻分佈的負數 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數爲普通的建模提供了一種獲取均勻分佈隨機數的機制，例如可用於數據鏈路協 議計算隨機超進。 4）錯誤 無錯誤捕獲 5）相關函數 採用 op_dist_load()加載一個概率分佈。 採用 op_dist_outcome()根據已加載的概率分佈，獲取一隨機值。

2.3 進程函數集 進程函數集是一系列用於在一個處理器或隊列模塊中創建和管理多個進程的核心函數的 集合。進程是進程模型的一個實例，進程模型是在 OPNET 的進程編輯器中開發的特定類型 進 程的行爲和功能規範。 1. op_pro_create (model_name, ptc_mem_ptr) 此核心函數的作用是創建一個新的進程作爲特定進程模型的實例，並允許安裝 parent-to-child 共享內存， 作爲當前進程和創建的子進程間通信機制， 其參數說明如表 2-7 所示。 表 2-7 參 數 model_name 類 型 const char* 進程模型名稱 當前進程和被創建進程共享的 parent-to-child 內存塊的地址 ptc_mem_ptr Vartype* （該內存塊格式是用戶自定義的。通常若無內存共享，則傳 遞值 OPC_NIL） op_dist_load()函數的參數說明 描 述

1）返回值 Prohandle——進一步處理被創建子進程的進程句柄。 2）詳解 仿真內核支持單個隊列或處理器模塊中任意多個不同類型進程的並存。除了根進程，其他 所有進程都通過該核心函數創建。 只有當提供的參數 process_model 引用當前仿真中已聲明的進 程，該核心函數纔會執行成功。在爲仿真系統的任一處理器或隊列模塊的進程模型屬性賦值， 或在通過進程編輯器將進程聲明爲另一進程的子進程時，均採用進程模型的隱式聲明。 每個通過該核心函數創建的進程都可以利用共享內存與創建它的進程進行通信。共享內存 是用戶自定義的內存塊，其地址必須作爲 ptc_mem_ptr 參數傳遞給該函數。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一個進程，其可以創建在相同模塊中操作的子進程。每個子進程作爲一 個進程模型實例獨立存在，並維持自身的狀態。 4）錯誤 Program Abort：核心函數需要進程上下文。 Program Abort：無法創建進程。 Program Abort：進程的描述符分配失敗。 Program Abort：初始化進程失敗。 Recoverable Error：進程模型未被聲明。 5）相關函數 採用 op_pro_invoke()調用進程模型。 子進程採用 op_pro_parmem_access()獲取 parent_to_child 共享內存。 採用 op_pro_id()確定進程的惟一整數標識符。

2. op_pro_destroy_options(pro_handle, options) 銷燬動態創建的進程和該進程的所有預設事件，其參數說明如表 2-8 所示。 表 2-8 參 數 pro_handle options 1）返回值 Compcode — — 表 示 仿 真 內 核 是 否 成 功 銷 毀 進 程 的 完 成 代 碼 ， 包 括 OPC_COMPCODE_SUCCESS 和 OPC_COMPCODE_FAILURE。 類 型 Prohandle int 被銷燬進程的進程句柄 被執行的可選操作 op_pro_destroy_options ()函數的參數說明 描 述

2）詳解 該函數允許進程銷燬同一模塊中的任意其他動態進程，因此跟進程是惟一給定模塊中不能 被銷燬的進程。此外，該函數還可移除被銷燬進程的所有預設事件。其中，動態進程是通過核 心函數 op_pro_create()創建的，在仿真中可隨時從模型中移除動態進程。 適當終止進程可釋放分配給進程的動態內存，但這也可能給建模帶來一定影響。進程模型 在銷燬時會有一個特殊的邏輯片斷，該片斷是進程模型的終止塊和銷燬進程時仿真內核直接調 用的包含其中的代碼。代碼片斷中可能用到狀態和臨時變量。 進程可以銷燬自身，這時不返回任何值，除了終止塊中的特定操作外，不執行任何操作。 注意：內核對釋放 parent-to-child 或參數內存不負任何責任。 該核心函數可使用的 option 有： ? OPC_PRO_DESTROY_OPT_KEEP_EVENTS——核心函數移除被銷燬進程的任意預 設事件。 ? OPC_PRO_DESTROY_OPT_NONE——默認操作。

此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一個進程，其可以創建在相同模塊中操作的子進程。每個子進程作爲一 個進程模型實例獨立存在，並維持自身的狀態。 4）錯誤 Program Abort：核心函數需要進程上下文。 Program Abort： 分段錯誤（由畸形進程句柄導致） 。 Recoverable Error：進程句柄無效。 Recoverable Error：進程句柄指向被銷燬進程。 Recoverable Error：進程句柄指向遠程進程。 Recoverable Error：進程句柄指向根進程。 Recoverable Error：進程句柄指向活動進程。 5）相關函數 採用 op_pro_create()創建新的進程並獲取其句柄。 採用 op_prg_mem_free()釋放通過函數 op_prg_mem_alloc()分配的內存。 採用 op_pro_invoke()調用進程模型。 採用 op_pro_parmem_access()用於子進程獲取 parent_to_child 共享內存。

3. op_pro_self() 此核心函數的作用是獲取當前正在執行的進程的進行句柄。

1）返回值 Prohandle——當前正在執行的進程的進程句柄。在執行與該進程相關的操作，調用其他核 心函數時可使用此句柄。 2）詳解 當前執行的進程通常需要使用其自身的句柄作爲進程和中斷函數集中其他核心函數的參 數。例如，該句柄可作爲指針來獲取父進程的句柄。其他典型應用包括獲取進程的惟一 ID，銷 毀無用的進程本身。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數爲調用該核心函數的進程提供了一個進程句柄，作爲進程和中斷函數集中其他 核心函數的參數。 4）錯誤 Program Abort：核心函數需要進程上下文。 5）相關函數 採用 op_pro_id()獲取進程的惟一整數 ID。 採用 op_prg_mem_free()銷燬進程。 採用 op_intrpt_port_register ()爲特定流或統計中斷註冊一個進程。 採用 op_intrpt_type_register()爲特定類型中斷註冊一個進程。

4. op_pro_invoke (pro_handle, argmem_ptr) 該核心函數的作用是在當前事件和當前模塊的止下文中調用進程。被調用進程將被暫停直 到函數返回，其參數說明如表 2-9 所示。 表 2-9 參 數 pro_handle argmem_ptr 1）返回值 Compcode——表示調用是否成功的完成代碼， 返回代碼包括 OPC_COMPCODE_SUCCESS 和 OPC_COMPCODE_FAILURE。進程句柄過期或調用其他模塊的進程都將引起調用失敗。 2）詳解 進程可調用同一模塊中的其他進程。如果使用其他模塊進程的進程句柄來調用該函數將引 起可恢復錯誤。 類 型 Prohandle Vartype* 被調用進程的進程句柄 通過函數 op_pro_argmem_access()爲被調用進程提供的參數 內存塊的地址 op_pro_invoke()函數的參數說明 描 述

在同一事件中，對函數 op_pro_invoke()的調用次數並沒有任何限制。換句話說，調用函數 op_pro_invoke()所導致中斷的進程，可接着利用該函數調用其他進程。這種一連串的進程調用 稱爲當前調用棧，就像 C 語言中的函數調用棧一樣。仿真內核限制進程在當前調用棧中調用其 他進程。 當進行進程調用時，調用進程可建立一個內存塊，供它和被調用進程共享。由於該內存可 傳遞被調用進程的輸入和輸出參數，因而作爲參數內存。若調用進程需要通過函數 op_pro_argmem_access()來獲取內存塊地址，則地址必須作爲參數傳遞給 op_pro_invoke()；若無 此需要，則應傳遞常量 OPC_NIL。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 多個進程可共同處理單一隊列或處理器模塊上下文中發生的事件。通常對進程進行分層組 織，父進程根據不同事件的要求將事件處理任務交給合適的子進程。另外一種進程組織方式就 是根據功能行來劃分任務，如可根據進程收到的中斷類型調用不同的子進程。大多數組織化機 制都有一個共通處，即都需要在模塊中臨時傳遞對子進程或對等進程的執行控制權。這就需要 通過函數 op_pro_invoke()來完成，並提供需執行的進程句柄。 4）錯誤 Program Abort：核心函數需要進程上下文。 Program Abort： 分段錯誤（由畸形進程句柄導致） 。 Recoverable Error：進程句柄無效。 Recoverable Error：進程句柄指向被銷燬進程。 Recoverable Error：進程句柄指向遠程進程。 Recoverable Error：進程句柄指向活動進程。 5）相關函數 採用 op_pro_argmem_access()獲取調用參數內存的訪問權。 採用 op_pro_parent()獲取父進程的進程句柄。 採用 op_pro_create()創建新的進程並獲取其句柄。

5. op_pro_argmem_access () 此函數的作用是獲取進程調用所傳遞的參數內存的地址。 1）返回值 Vartype*——調用進程提供的用戶自定義內存塊的地址。若仿真內核直接調用進程或調用 進程不願傳遞任何參數內存，則返回符號常量 OPC_NIL。 2）詳解

參數磪存是一個用戶自定義的內存塊，其地址由進程調用其他進程時傳遞。內存的格式和 內容都是用戶自定義的，只有其地址由仿真內核管理。仿真內核保證只有通過函數傳遞的內存 地址阻塞時，才能被調用進程訪問，並將控制權返回給調用進程。 地於直接由仿真內核調用的進程，該核心函數將返回一個空地址 OPC_NIL。直接由內核 調用的進程和通過函數 op_pro_invoke()調用的進程應在使用該指針訪問參數值之前檢查返回的 地址是否爲 OPC_NIL，否則將發生分段錯誤。 調用函數 op_pro_invoke()可使用參數內存機制，這時被調用進程並不需要接收傳入的值或 向調用進程返回任何數據。在這種情況下，通常在需要參數內存的情況下，調用函數 op_pro_invoke()應傳遞符號常量 OPC_NIL。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種在調用進程和被調用進程間共享內存的機制。內存可在調用前建 立，以包含輸入參數值。被調用進程可以檢查檢查該參數值，並利用它來處理事件。同樣被調 用進程可修改內存，以向調用進程返回輸出參數，而調用進程可在函數 op_pro_invoke()返回之 後檢查內存的內容。 該核心函數提供了一種在調用進程和被調用進程間共享內存的機制。內存可在調用前建 立，以包含輸入參數值。被調用進程可以檢查該參數值，並利用它。 4）錯誤 Program Abort：核心函數需要進程上下文。 5）相關函數 採用 op_pro_invoke()調用進程模型。 採用 op_pro_modmem_access()與同一模塊中的其他進程共享信息。 採用 op_pro_parmem_access()與進程及其父進程共享信息。

2.4 事件函數集 op_ev_cancel(evhandle) 函數的作用是撤銷預設的事件，其參數說明如表 2-10 所示。 表 2-10 參 數 evhandle 類 型 Evhandle op_ev_seek_time()、op_ev_next()、op_intrpt_schedule_self()等函數獲取 op_ev_cancel()函數的參數說明 描 述

被取消事件的事件句柄。事件句柄可以通過本函數集中的

1）返回值

Compcode——表示操作是否成功的完成代碼， 包括符號常量 OPC_COMPCODE_SUCCESS 和 OPC_COMPCODE_FAILURE。 2）詳解 取消事件就是將其從仿真事件列表中移除，並阻止其向目的模塊發送。該函數只能用於取 消未決的事件，取消已經發送或正在執行的事件將導致錯誤發生。 因爲仿真內核將事件信息緩存到了相應的事件句柄中，這樣無需查找就可很快對事件進行 定位，所以利用該函數取消事件時不必考慮效率問題。在事件發送之前使用該函數將其取消將 比事件發送到目的地後再將其取消更加高效。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種撤銷無用事件的機制。該函數常用於取消 op_intrpt_schedule_self() 函數預設的超時中斷事件。如果在超時前收到 ack 包或有其他中斷髮生，則該函數將取消超時 事件，並重置定時器。 4）錯誤 Program Abort： 分段錯誤（由畸形進程句柄導致） 。 Recoverable Error：事件句柄指向無效或當前還未預設的事件。 Recoverable Error：無法取消當前事件。 Recoverable Error：無法取消正在進行的事件。 Recoverable Error：無法取消未定位事件。 5）相關函數 採用 op_ev_pending()確定事件是否可取消。 採用 op_intrpt_schedule_self()設置進程的自中斷。 採用 op_intrpt_clear_self()撤銷進程的未決中斷。

2.5 仿真函數集 1. op_sim_time() 此函數的作用是獲取當前仿真時間。 1）返回值 double——當前仿真時間。該雙精度浮點數以秒爲單位表示了當前的仿真時間，從仿真中 斷（即 op_sim_time()返回零值）時刻開始計時。 2）詳解 仿真時間是一個雙精度浮點數，表示與當前仿真事件相關的時間值。在處理一個事件時， 仿真時間始終保持原值， 只有當在 T 時刻完成了該事件並在 T+dt 時刻開始另一個事件時， 仿真

纔開始繼續計時。我們將這種使用不規則模式計時的仿真方法稱爲事件驅動的仿真方法（區別 於規則的時間驅動的仿真方法） 。 在仿真開始執行事件之前，無線發信機模塊的收信機組管道階段調用該函數，或無線域中 初始回叫信號過程調用該函數時，該函數都將返回“-1” 。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種獲取當前仿真時間的機制，可用於將來預設事件時計算絕對時間； 確定過去某事件相對於當前仿真時間的延時；在標準輸出設備或其他輸出文件中打印帶時間標 記的診斷信息和調試語句。 4）錯誤 該函數無錯誤捕獲。 5）相關函數 採用 op_intrpt_schedule()、 op_intrpt_schedule_remote()或 op_intrpt_schedule_call()預設中斷。 採用 op_pk_creation_time_get()或 op_pk_stamp_time_get()從包中獲取時間值與當前仿真時 間進行比較。 採用 op_q_wait_time()或 op_q_insert_time()從隊列模塊中的包裏獲取隊列延時信息。

2. op_sim_end(line0,line1,line2,line3) 此核心函數的作用是終止仿真，關閉矢量輸出文件並打印指定行，其參數說明如表 2-11 所示。 表 2-11 op_sim_end()函數的參數說明 參 數 line0 line1 line2 line3 1）返回值 Void——無返回值。 2）詳解 該函數在時間到期前終止仿真，同時所有激活了 endsim intrpt 屬性的處理器和隊列的都將 收到終止仿真中斷。 當 OPNET 仿真工具正在運行仿真時，儘管四個指定行在直接指向 shell 的輸出中都可見， 但同時只有前三行可以顯示的消息窗口中。 類 型 const char* const char* const char* const char* 消息行#0 消息行#1 消息行#2 消息行#3 描 述

此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數基於可調用該函數的進程的動態狀態，提供了一種有條件仿真的機制，通常應 用在以下兩類環境中： 一個異常錯誤環境被仿真邏輯捕獲，使得以後的仿真沒有必要繼續進行； 仿真邏輯發現基於仿真完畢狀態的統計收斂或其他度量形式的仿真停止的情況。 在任一種模式下，有效終止仿真都非常必要，因爲這樣仿真中被寫進的矢量、標量輸出文 件就可以正常這完成並關閉。 4）錯誤 Program Abort： 分段錯誤（由無效或畸形消息串引起） 。 5）相關函數 採用 op_sim_time()確定當前仿真時間。 採用 op_stat_scalar_write()寫出總結仿真結果的標量統計量值。 採用 op_sim_message()在標準輸出設備中打印消息但不終止仿真。

2.6 鑑定函數集 Id（Identification）函數集是獲取仿真對象 ID 的核心函數的集合。對象 ID 對於核心函數非 常重要，因爲大多數與對象操作相關的核心函數都需要使用對象 ID。對象 ID 是一個惟一標識 仿真中某對象的整數， 所有的仿真對象共享一個共同的對象 ID 編號空間。 例如不管是節點還是 隊列，都只能有一個 ID 爲 5 的對象。

op_id_self() 此函數可獲取所屬處理器或隊列的對象 ID。 1）返回值 Objid——所屬處理器或隊列的對象 ID。如果核心函數由非進程上下文調用，則返回符號 常量 OPC_OBJID_INVALID。 2）詳解 如果該函數由非進程上下文（如運行在處理器或隊列中的進程）調用，則返回符號常量 OPC_OBJID_INVALID。通過 op_intrpt_schedule_call()接口執行的預設過程調用，將繼承調用進 程的上下文。因此，如果進程預設了一個過程調用，那麼過程調用將收到 op_id_self()返回的有 效值。但管道階段並不作爲進程上下文，因此將返回 OPC_OBJID_INVALID。 此外，該核心函數的安全級別爲 MT-safe。 3）目的

該核心函數爲進程提供了一種獲取其自身對象 ID 的機制。有了自己的 ID，進程就可通過 核心函數 op_ima_obj_attr_get()訪問自己的屬性值。此外，還可連續調用函數 op_topo_parent() 來獲取所屬節點或子網的對象 ID。 op_id_self()也可用於測試當前上下文是否屬於某一進程，如果不屬於，則返回常量 OPC_OBJID_INVALID。 4）錯誤 該核心函數無錯誤捕獲。 5）相關函數 採用 op_topo_parent()獲取父對象 ID。 採用 op_topo_child()獲取子對象 ID。 採用 op_ima_obj_attr_get()獲取對象屬性值。 採用 op_ima_obj_attr_set()設置對象屬性值。

2.7 拓撲函數集 Topo(Topology)函數集是確定節點和網絡模型拓撲結構的核心函數的集合。利用這類核心 函數，進程模型在被寫入時可以自動配置以符合其所屬環境。 1. op_topo_parent (child_objid) 此核心函數的作用是獲取給定對象的父對象 ID，其參數說明如表 2-12 所示。 表 2-12 op_topo_parent()函數的參數說明 參 數 類 型 描 述

子對象 ID（對象 ID 可通過 Id 函數集裏的函數 op_id_self()、 op_id_from_userid()或 op_id_from_name()獲取，也可通過調用 child_objid Objid 本 函 數 集 裏 的 函 數 op_topo_parent() 、 op_topo_child() 、 op_topo_assoc()和 op_topo_connect()來獲取。 ） 1）返回值 Objid——父對象 ID。如果參數 child_objid 爲最高級別的子網 ID，則返回符號常量 OPC_OBJID_NULL；如果發生可恢復錯誤，將返回符號常量 OPC_OBJID_INVALID。 2）詳解 連續調用該核心函數可用於提示對象層次結構。例如在一個五級對象仿真中，可利用子隊 列對象 ID，通過連續五次調用該函數來獲取最高級別的子網（對象 ID=0） ，程序如下所示： subq_comp_attr_objid=op_topo_parent(subqueue_objid); queue_objid=op_topo_parent(subq_comp_attr_objid); node_objid=op_topo_parent(queue_objid);

subnet_objid=op_topo_parent(node_objid); top_subnet_objid=op_topo_parent(subnet_objid); 注意：subq_comp_attr_objid 是複合屬性的嵌入類型。對於用戶自定義的算命屬性有： comp_attr_objid= op_topo_parent(generic_objid) path 沒有父對象，因此若 child_obj_hndl 指向一個 path 對象，則該函數將返回一個無效句 柄。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種已知低層對象 ID， 需要對高層對象進行操作時， 提升對象層次結構 的機制。通常，該核心函數用於獲取包含運行調用進程的處理器或隊列的節點（或子網）ID。 在獲取了節點或子網的對象 ID 後，就可通過 op_ima_obj_attr_get()獲取它們的屬性值。 4）錯誤 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採用 op_id_self()獲取所屬處處理器或隊列模塊的對象 ID。 採用 op_topo_child()獲取另一對象的子對象 ID。 採用 op_ima_obj_attr_get()獲取對象屬性值。 採用 op_ima_obj_attr_set()設置對象屬性值。

2. op_topo_child_count (parent_objid, child_type) 此核心函數的作用是獲取給定父對象中指定類型的子對象的數目，其參數說明如表 2-13 所示。 表 2-13 參 數 parent_objid child_type 1）返回值 int——給定父對象中指定類型的子對象的數目。 如果父對象不支持指定類型的子對象或父 對象 ID 無效，則將返回符號常量 OPC_OBJID_INVALID。 2）詳解 仿真對象通常包含的子對象如表 2-14 所示。 表 2-14 op_topo_child_count ()函數的參數說明 類 型 Objid int 父對象 ID 相關子對象類型 op_topo_child_count ()函數的參數說明 描 述

仿真對象 子網 節點 隊列 收信機 發信機 複合屬性

所 含 子 對 象 子網、節點、鏈路和接頭 模塊、流和統計線 子隊列複合屬性 收信機信道複合屬性對象 發信機信道複合屬性對象 普通子對象、子隊列、收信機信道和發信機信道

通常仿真對象並不包含以下子對象：單工和雙工方式的點到點鏈路、總線鏈路、總線鏈路 接頭、處理器和天線。 path 沒有子對象，也不屬於任何子網，因此如果參數 parent_object 指向一個 path 對象或參 數 child_type 等於 OPC_OBJTYPE_PATH，則該核心函數將返回零。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種確定父對象包含的子對象數目的機制。 可利用父對象 ID、 定義對象 類型的符號常量和環路索引來調用函數 op_topo_child()，以獲取每個子對象的對象 ID。 4）錯誤 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象類型不可識別。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採用 op_topo_child()根據索引來獲取子對象 ID。 採用 op_topo_object_count()確定特定類型對象的數目。 採用 op_topo_assoc_count()獲取輸入和輸出關聯的數目。

3. op_topo_child (parent_objid, child_type, child_index) 此核心函數的作用是獲取具有指定類型和索引的子對象 ID，其參數說明如表 2-15 所示。 表 2-15 參 數 parent_objid child_type child_index 類 型 Objid int int 父對象 ID 子對象類型 子對象索引（子索引從零開始逐一遞增，最大不超過本類 子對象的總數減一） op_topo_child ()函數的參數說明 描 述

1）返回值 Objid——子對象 ID。如果發生可恢復錯誤，將返回符號常量 OPC_OBJID_INVALID。 2）詳解 確定子對象需要兩個參數：子對象類型和子對象索引。連續調用該函數可降低對象的層次 結構。 例如在一個五級對象仿真中， 可能過連續五次調用該函數將最高級別的子網 （對象 ID=0） 轉換爲子隊列對象 ID，程序如下所示： subnet_objid=op_topo_child(top_subnet_objid, OPC_OBJTYPE_SUBNET_FIX, 0); node_objid=op_topo_child(subnet_objid, OPC_OBJTYPE_NDFIX, 0); queue_objid=op_topo_child(node_objid,OPC_OBJTYPE_QUEUE, 0); subq_comp_attr_objid=op_topo_child(queue_objid, OPC_OBJTYPE_COMP, 0); subqueue_objid=op_topo_child(subq_comp_attr_objid, OPC_OBJTYPE_SUBQ, 0); 注意，subq_comp_attr_objid 是複合屬性的嵌入類型。對於用戶自定義的複合屬性有： Generic_objid=op_topo_child(comp_attr_objid, OPC_OBJTYPE_GENERIC, 0); path 沒有子對象，也不屬於任何子網，因此若 parent_obj_hndl 指向一個 path 對象或 child_type 等於 OPC_OBJTYPE_PATH，則該核心函數將返回一個空句柄。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種已知高層對象 ID， 需要對低層對象進行操作時， 降低對象層次結構 的機制。 該函數通常用於獲取已知發信機或收信機的信道 ID， 從而通過函數 op_ima_obj_attr_get() 或 op_ima_obj_attr_set()來獲取信道屬性值或爲其賦值。該函數還可用於獲取節點中的模塊 ID， 但通常使用名稱而不是索引值來確定子對象的函數 op_id_from_name()。該函數也可用於獲取用 戶自定義的複合屬性和其子對象 ID。 4）錯誤 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象類型不可識別。 Recoverable Error：對象無子對象。 Recoverable Error：對象索引溢出。 Recoverable Error：子索引超過指定類型子對象。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採用 op_topo_child_count()確定對象的子對象數目。 採用 op_ima_obj_attr_get()獲取對象屬性值。 採用 op_ima_obj_attr_set()設置對象屬性值。

採用 op_topo_object()獲取對象 ID。 採用 op_topo_parent()獲取父對象 ID。 採用 op_id_from_name()通過名稱獲取子對象 ID。

4. op_topo_assoc (objid, direction, objmtype, index) 此核心函數的作用是獲取具有指定類型、 方向和索引的對象關聯 ID， 其參數說明如表 2-16 所示。 表 2-16 參 數 objid 類 型 Objid 對象 ID 關聯的方向： OPC_TOPO_ASSOC_IN：輸入關聯 direction int OPC_TOPO_ASSOC_OUT：輸出關聯 OPC_TOPO_ASSOC_THROUGH：吞吐率關聯 objmtype index 1）返回值 Objid — — 輸 入 / 輸 出 關 聯 的 對 象 ID 。 如 果 發 生 可 恢 復 錯 誤 ， 則 返 回 符 號 常 量 OPC_OBJID_INVALID。 2）詳解 所謂對象的輸入/輸出關聯，就是直接與輸入/輸出端口或在節點處開始/結束的路徑相連的 對象。表 2-17 列出了有效的對象和關聯類型。 int int 關聯的對象 meta-type 關聯的數值索引（從零開始，逐一遞增） op_topo_assoc ()函數的參數說明 描 述

表 2-14 對象類型 site(fixed subnet; fixed site, link, path node) link(bus;simplex; site receiver duplex; pt-pt link) 輸 入

對象和關聯類型 輸 出 經 由

site, link, path

path

site receiver

path all attached nodes/links,

path

site (head/tail)

site(head/tail)

all demands flowing through

demand module(processor,

site(destination) module connection

site(source) module

all path used none

queue, and so on) connection(stream, module statistic wire) transmitter(pt-pt, bus, module connection radio) receiver(pt-pt, bus, link transmitter radio) tap bus transmitter bus receiver bus bus, bus transmitter

connection module none

link receiver module

none

none connection bus,bus none receiver tap none tap none none none

none tap tap

在無線建模中，移動站點和衛星站點不能與點到點鏈路或總線鏈路相連，因此只能是中由 關聯和需求關聯。同樣，無線域也沒有關聯。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種已獲取與輸入/輸出對象相關聯的對象關聯的對象 ID 的機制。該函 數主要用於進程需要獲取鉕設置鄰近對象屬性的情況下，如在發信機相連的處理器上運行的進 程，可能需要週期性地改變發信機信道的頻率；或進程可能質詢輸出點到點鏈路的屬性。 4）錯誤 Recoverable Error：對象 ID 溢出。 Recoverable Error：關聯方向不可識別。 Recoverable Error：對象 meta-type 不可識別。 Recoverable Error：關聯索引溢出。 Recoverable Error：對象類型不支持關聯。 Recoverable Error：對象不支持關聯方向。 Recoverable Error：關聯索引超過關聯類型。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採用 op_topo_assoc_count()確定對象擁有的關聯數目。 採用 op_ima_obj_attr_get()獲取對象屬性值。

5. op_topo_assoc_count (objid, direction, objmtype) 此核心函數的作用是獲取具有特定類型和和對象的關聯數目，其參數說明如表 2-18 所示。 表 2-18 參 數 objid 類 型 Objid 對象 ID 關聯的方向： direction int OPC_TOPO_ASSOC_IN：輸入關聯 OPC_TOPO_ASSOC_OUT：輸出關聯 objmtype 1）返回值 Objid — — 特 定 方 向 和 類 型 的 關 聯 數 目 。 若 發 生 可 恢 復 錯 誤 ， 則 返 回 符 號 常 量 OPC_OBJID_INVALID。 2）詳解 對象的輸入/輸出關聯，是直接與輸入/輸出端口相連的對象，參看表 2-17。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種確定對象擁有的輸入/輸出關聯的數目的方法。 這對於設置關聯對象 的環路範圍很有用。 可根據對象 ID 和環路索引調用函數 op_topo_assoc()來獲取每個關聯的對象 ID。 4）錯誤 Recoverable Error：對象 ID 溢出。 Recoverable Error：關聯方向不可識別。 Recoverable Error：對象 meta-type 不可識別。 Recoverable Error：對象類型不支持關聯。 Recoverable Error：引用對象不支持關聯方向。 Recoverable Error：對象 ID 指向受限對象。 5）相關函數 採用 op_topo_assoc ()獲取輸入/輸出關聯的對象 ID。 採用 op_ima_obj_attr_get()獲取對象屬性值。 採用 op_ima_obj_attr_set()設置對象屬性值。 採用 op_topo_child_count()確定子對象數目。 採用 op_topo_object_count()確定特定類型的對象數目。 int 關聯的對象 meta-type op_topo_assoc_count ()函數的參數說明 描 述

2.8 接口控制信息函數集 ICI（Interface Control Information）函數集是與 ICI 仿真實實體相關的核心函數的集合。ICI 是內部進程通信所傳遞的數據的結構化集合。若進程在中斷髮生之前建立 ICI，則 ICI 就與中 斷關聯起來了。 主要用於分層協議的接口連接， ICI 也可用於關聯複雜的自中斷或點到點遠程中 斷的信息。 1. op_ici_create(fmt_name) 此核心函數的作用是創建一個具有預定義 ICI 格式的 ICI，其參數說明如表 2-19 所示。 表 2-19 參 數 fmt_name 1）返回值 Ici*——指向新創建的 ICI 的指針。若發生可恢復錯誤，則返回常量 OPC_NIL。 2）詳解 新的 ICI 由仿真內核分配， 該函數返回它的指針並允許原始進程指定 ICI 屬性。ICI 格式是 預先定義的固定結構，由一系列屬性名稱和類型按序組成。除非調用函數 op_ici_install()，否則 新創建的 ICI 不會自動影響預設中斷。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數爲進程模型提供了一種創建新的 ICI 與鄰居進程進行通信的機制。如果進程模 型每次預設中斷時都改變 ICI 的屬性，並且在傳遞中斷前又預設新的中斷，那麼它應爲每個預 設中斷創建一個新的 ICI。換句話說，如果兩個進程模型採用一系列未延遲的 ICI-bearing 中斷 進行通信，那麼中需要在開始仿真時爲單向通信創建一個 ICI（或爲雙向通信創建兩個 ICI） 。 4）錯誤 Program Abort：內存分配失敗（由於內存不足以滿足新創建的 ICI 或其屬性而引起） 。 Program Abort：核心數需要進程上下文。 Recoverable Error：ICI 格式不可識別 5）相關函數 採用 op_ici_destroy()銷燬 ICI。 採用 op_ici_attr_set()爲 ICI 屬性賦值。 採用 op_ici_install(0 創建一個與輸出中斷相關聯的 ICI。 採用 op_ici_format_print_set()打印給定格式 ICI 的指定結構字段。 類 型 const char* op_ici_create ()函數的參數說明 描 述

被創建 ICI 的格式名稱 （該值必須爲已定義的 ICI 格式名稱， 否則將出錯。 ）

2. op_ici_destroy(iciptr) 此核心函數的作用是解除已分配的 ICI，並釋放相應的內存資源，其參數說明如表 2-20 所 示。 表 2-20 參 數 類 型 op_ici_destroy ()函數的參數說明 描 述

指向給定 ICI 的指針（可以通過兩個核心函數來獲取 ICI 指 針：在 ICI 發送進程中，函數 op_ici_create()返回新創建 ICI iciptr Ici* 的指針：在 ICI 接收進程中，函數 op_intrpt_ici()返回與輸入 中斷相關的 ICI 指針） 1）返回值 Void——無返回值。 2）詳解 當不再使用某個 ICI 時，就應當釋放分配給它的內存資源，以用來創建新的 ICI。若在仿 真內核心釋放 ICI 內存資源時出錯，將導致無用的 ICI 持續佔用虛擬內存。虛擬內存被完全佔 用後，將無法滿足創建其他新對象的需要，則仿真異常結束。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種重複利用分配給無用 ICI 的內存的機制。仿真內核可自由地按需將 內存分配給其他動態對象。調用該函數後，給定 ICI 的指針就應視爲無效。 4）錯誤 Program Abort：分段錯誤（由無效 ICI 指針或畸形 ICI 數據結構引起） 。 Recoverable Error：ICI 指針爲 NIL。 5）相關函數 採用 op_ici_create()創建 ICI。 採用 op_intrpt_ici()獲取與輸入中斷相關的 ICI 指針。 採用 op_ici_attr_set()爲 ICI 屬性賦值。 採用 op_ici_install()創建一個與輸出中斷相關聯的 ICI。

3. op_ici_attr_get(iciptr, attr_name, value_ptr) 此核心函數的作用是獲取給定 ICI 的某屬性值，其參數說明如表 2-21 所示。

表 2-21

op_ici_attr_get ()函數的參數說明

參 數 iciptr attr_name value_ptr 1）返回值

類 型 Ici* const char* Vartype* 指向給定 ICI 的指針 屬性名

描

述

指向變量的指針，該變量中存儲了將賦給指定屬性的值。

Compcode——表示是否成功獲取 ICI 屬性值的完整代碼，如果發生可恢復錯誤，則返回 OPC_COMPCODE_FAILURE。 2）詳解 給定的屬性名必須是 ICI 引用的格式中定義過的屬性。注意，函數返回的是屬性的當前內 容，而不是創建 ICI 或預設相關中斷時的屬性內容。 進程模型是通過指針和不同的包來操作 ICI 的，並沒有 ICI 所有權的概念。也就是說，幾 個進程模型可能同時訪問同一 ICI 數據結構，因此可能會互相干擾。當多個事件都處理同一 ICI 時，修改 ICI 將影響 ICI 在之前事件中的使用。例如，如果一個進程創建了一個 ICI，爲其屬性 賦值，將其安裝，接着發送了一個包，並在包收到之前修改了 ICI 的一個屬性，那麼值將是進 程模型收到包時通過函數 op_ici_attr_get()訪問 ICI 獲取的值。 在聲明參數 value_ptr 時必須注意， value_ptr 不僅要具有正確的數據類型， 還必須是指向可 用內存的有效指針，因此該參數通常都使用 C 語言的地址操作符“&” 。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種進程收到與 ICI 相關的中斷並確定 ICI 屬性值的機制。 由於一個 ICI 可被多個進程共享，因而它可用於多路通信。這裏進程收到一箇中斷，從 ICI 中獲取控制信息， 並能過在 ICI 中設置屬性來返回信息。因爲返回值可立即被初始進程訪問，所以通常可與強制 中斷結合使用。 4）錯誤 Program Abort：分段錯誤（由無效 ICI 指針、畸形 ICI 數據結構或聲明出錯的 value_ptr 參 數引起） Recoverable Error：屬性名稱在 ICI 格式中不可識別 5）相關函數 採用 op_intrpt_ici()獲取與輸入中斷相關的 ICI 指針。 採用 op_ici_attr_exists()確定在 ICI 格式中是否存在某屬性。 採用 op_ici_attr_set() 設置 ICI 屬性值。 採用 op_ici_destroy()銷燬無用 ICI。 採用 op_ici_print()在標準輸入設備上打印 ICI 內容。

4. op_ici_attr_set(iciptr,attr_name, value) 此核心函數的作用是爲給定 ICI 某屬性賦值，其參數說明如表 2-22 所示。 表 2-22 參 數 iciptr attr_name value 1）返回值 Compcode——表示 ICI 屬性值是否成功修改的完成代碼，如果發生可恢復錯誤，則返回 OPC_COMPCODE_FAILURE。 2）詳解 給定的屬性名必須是 ICI 引用的格式中定義過的屬性。通過該函數所賦的值將覆蓋之前分 配的值，而任何具有該 ICI 指針的進程都可訪問新的屬性值。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了進程中設置 ICI 內容並與其他進程進行通信的機制。新創建的 ICI 和已 經發送到目的進程的 ICI 都可以進行屬性設置。ICI 通過強制中斷來執行雙向通信，這樣初始進 程就可立即獲取結果。 4）錯誤 Program Abort：分段錯誤（由無效 ICI 指針、畸形 ICI 數據結構或聲明出錯的 value_ptr 參 數引起） Program Abort：核心函數需要進程上下文。 Recoverable Error：屬性名稱在 ICI 格式中不可識別 5）相關函數 採用 op_ici_attr_get() 獲取 ICI 屬性值。 採用 op_ici_create()創建 ICI。 採用 op_ici_install()建立一個與輸出中斷相關的 ICI。 採用 op_ici_attr_exists()確定在 ICI 格式中是否存在某屬性。 類 型 Ici* const char* Vartype* 指向給定 ICI 的指針 給定屬性的名稱 爲給定屬性所賦的值 op_ici_attr_set ()函數的參數說明 描 述

5. op_ici_install(iciptr) 此核心函數的作用是建立一個 ICI，使其自動與調用進程預設的輸出中斷相關聯，其參數 說明如表 2-23 所示。

表 2-23 參 數 iciptr 1）返回值 類 型 Ici*

op_ici_install ()函數的參數說明 描 述

指向給定 ICI 的指針

Ici*——建立的 ICI，如果爲空則返回 OPC_NIL。 2）詳解 任何時候，最多隻能爲一個進程建立一個 ICI。隊列/處理器模塊中的進程各自維持自己建 立的 ICI。建立 ICI 將通知仿真內核所有調用進程預設中斷都應標記給定 ICI 的指針，這使得很 多預設中斷不需要打標記並創建一個新的 ICI 就可自動與 ICI 關聯。 在中斷預設到中斷傳遞這段時間內， 不管 ICI 發生什麼變化 （包括修改 ICI 內容或銷燬 ICI） ， 預設中斷都將始終維持與 ICI 的關聯。在這種情況下，進程在收取中斷時可能還將收到其他額 外信息。爲了避免這種情況，通常發送進程爲每個中斷都創建並建立一個 ICI，而接收進程就應 當擔負起銷燬進程的責任。 即使處理中斷並不需要與之相關的 ICI，但將 ICI 與中斷保持關聯也不會產生什麼壞處， 因此並沒有顯式提供解除建立 ICI 的函數。直到需將輸出中斷與另一個 ICI 關聯時，才需要解 除建立的當前 ICI。不過通過將常量 OPC_NIL 傳遞給參數 iciptr，可以用來解除 ICI 的建立，從 而阻止與輸出中斷的關聯。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種 將預設 ICI 與輸出中斷相關聯的機制。 每個進程都維持一個指向被 建立 ICI 的內部指針，則建立的 ICI 在非強制狀態及多處理機調用中都是有效的。 4）錯誤 Program Abort：分段錯誤（由無效 ICI 指針或畸形 ICI 數據結構引起） Program Abort：核心函數需要進程上下文。 5）相關函數 採用 op_ici_create()創建 ICI。 採用 op_ici_attr_get()獲取 ICI 屬性值。 採用 op_ici_attr_set()設置 ICI 屬性值。

2.9 中斷函數集 Intrpt(Interrupt)函數集是提供具有輸入中斷信息的進程並可預設輸出中斷的核心函數的集 合。

1. op_intrpt_schedule_self (time, code) 此核心函數的作用是爲調用進程預設一箇中斷，其參數說明如表 2-24 所示。 表 2-23 參 數 time 類 型 double op_ici_install ()函數的參數說明 描 述

預設的中斷時間 （該值爲絕對仿真時間， 而不是當前仿真時間的時延） 與中斷關聯的用戶自定義數值代碼（該值是一個完全由用戶自定義的

code

int

整數值，可作爲預設中斷的標識代碼。當中斷調用進程時，可通過函 數 op_intrpt_code()獲取該代碼）

1）返回值 Evhandle——預設中斷的事件句柄。該返回值可存儲在一個狀態變量中，以用於以後調用 函數 op_ev_cancel()時取消中斷。 2）詳解 調用該函數時將在仿真事件列表中加入一個代表預設自中斷的新事件。一旦預設了事件， 函數將立即返回調用進程的控制權。在延時期間，調用進程可自由進行其他任何活動。如果沒 有其他高優先級事件，預設的事件將會按時發生。當執行完所有的前期事件後且自中斷事件位 於仿真事件列表的表頭時，即將其仿真時間設爲當前仿真時間並執行事件，引發調用進程的自 中斷。進程可通過函數 op_intrpt_code()獲取與中斷相關的代碼。 當自中斷表示超時或其他類似事件時，有必要取消無用的自中斷。如在超時前收到了 ack， 則重置計時器。該函數返回的事件句柄將存儲在一個狀態變量中，將來就可利用該事件句柄調 用函數 op_ev_cancel()來取消中斷，程序如下所示： /*Sstate variable declaration*/ Evhandle \evh;

/*Self interrupt scheduling*/ evh=op_intrpt_schedule_self(sch_time,5);

/*Self interrupt canceling.*/ op_ev_cancel(evh); 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了預設自中斷的機制，常用來限制某個進程狀態的持續時間。當模擬超時 時，狀態將保持在等待包的到達，而超時自中斷就表示該狀態的結束。當模擬延時時，狀態將 保持在執行任務，而“結束任務”自中斷意味着任務完成並釋放資源。時間間隔結束後，進程

通常轉入空閒狀態或確定是否有其他未決任務需要執行。 4）錯誤 Program Abort：內存分配失敗。 Program Abort：核心函數需要進程上下文。 Recoverable Error：預設時間小於當前時間。 Recoverable Error：預設時間是一個無效的 double 值。 5）相關函數 採用 op_intrpt_schedule_remote()預設一個遠程中斷。 採用 op_intrpt_force_remote()強制預設遠程中斷。 採用 op_intrpt_schedule_call()預設一個過程中斷。 採用 op_ev_cancel()取消未決的自中斷、遠程中斷或過程中斷。 採用 op_intrpt_code()獲取與中斷相關的代碼。

2. op_intrpt_schedule_remote (time, code, mod_objid) 此核心函數的作用是爲給定處理器或隊列預設一個遠程中斷，其參數說明如表 2-25 所示。 表 2-25 參 數 time code 類 型 double int 預設的中斷時間 與中斷相關的用戶自定義數值代碼 給定處理器或隊列的對象 ID（處理器或隊列 ID 可通過 Id 函 mod_objid Objid 數集中的 op_id_self()、op_topo_child()和 op_id_from_name() 函數來獲取） 1）返回值 Evhandle——預設中斷的事件句柄。該返回值可存儲在一個狀態變量中，用於以後調用函 數 op_ev_cancel()時取消中斷。 2）詳解 調用該函數時將在仿真事件列表中加入一個代表預設自中斷的新事件。一旦預設了事件， 函數將立即返回調用進程的控制權。在延時期間，調用進程可自由進行其他任何活動。如果沒 有其他高優先級事件，預設的事件將會按時發生。當執行完所有的前期事件後且自中斷事件位 於仿真事件列表的表頭時，即將其仿真時間設爲當前仿真時間並執行事件，引發調用進程的自 中斷。進程可通過函數 op_intrpt_code()獲取與中斷相關的代碼。 該函數返回事件句柄並將其存儲在一個狀態變量中，當發生條件改變需要取消中斷時，可 以利用該事件句柄，調用函數 op_ev_cancel()取消預設的遠程中斷，程序如下所示： op_intrpt_schedule_remote()函數的參數說明 描 述

/*Sstate variable declaration*/ Evhandle \evh;

/*Remote interrupt scheduling*/ evh=op_intrpt_schedule_remote(stime,22,mod_objid);

/*Remote interrupt canceling.*/ op_ev_cancel(evh); 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了無需物理包流或統計線的連接，進程可遠程調用另一進程的機制，進程 可用它來警告另一進程某事件的發生。 注意：遠程中斷只能傳遞到處理器或隊列，否則將引發錯誤。 4）錯誤 Program Abort：內存分配失敗。 Recoverable Error：預設時間小於當前時間。 Recoverable Error：預設時間是一個無效的 double 值。 Recoverable Error：對象 ID 溢出。 Recoverable Error：對象類型錯誤。 5）相關函數 採用 op_intrpt_schedule_self()預設一個自中斷。 採用 op_intrpt_schedule_call()預設一個過程中斷。 採用 op_ev_cancel()取消未決中斷。 採用 op_intrpt_code()獲取與中斷相關的代碼。

3. op_intrpt_type () 此核心函數的作用是獲取調用進程的當前中斷類型。 1）返回值 int——當前中斷類型。 2）詳解 該函數返回的中斷類型包括： ? ? OPC_INTRPT_FAIL（節點或鏈路失敗中斷） ； OPC_INTRPT_RECOVER（節點或鏈路失敗中斷） ；

? ? ? ? ? ? ? ? ? ? ?

OPC_INTRPT_PROCEDURE（過程中斷） ； OPC_INTRPT_SELF（自中斷） ； OPC_INTRPT_STRM（流中斷） ； OPC_INTRPT_REGULAR（常規中斷） ； OPC_INTRPT_STAT（統計中斷） ； OPC_INTRPT_REMOTE（遠程中斷） ； OPC_INTRPT_BEGSIM（仿真起始中斷） ； OPC_INTRPT_ENDSIM（仿真結束中斷） ； OPC_INTRPT_ACCESS（訪問中斷） ； OPC_INTRPT_PROCESS（進程中斷） ； OPC_INTRPT_MCAST（廣播中斷） ；

此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種機制來確定是何原因“喚醒”調用進程。該函數是最基本的核心函 數，幾乎每個進程模型都會使用它。進程模型大多都有一個或多個“分支狀態” ，分支狀態將該 過程返回的值存儲在一個臨時變量中，然後根據該返回值來選取輸出轉換。 4）錯誤 該核心函數無錯誤捕獲。 5）相關函數 採用 op_intrpt_code()確定與當前中斷相關的代碼。 採用 op_intrpt_strm()確定與當前中斷相關的流索引。 採用 op_intrpt_stat()確定與當前中斷相關的輸入統計索引。 採用 op_intrpt_ici()獲取與當前中斷相關的 ICI。

4. op_intrpt_strm () 此核心函數的作用是獲取與調用進程當前中斷相關聯的流索引。 1）返回值 int——與當前中斷相關聯的流索引。當使用函數 op_pk_deliver…()將包傳遞到指定輸入流 時，將顯式設置該值；當使用函數 op_pk_send…()向包流中發送包或通過函數 op_strm_access() 訪問包流時，將隱式設置該值。 2）詳解 在與流相關聯的中斷後調用該函數，將只產生一個有效值。與流相關聯的中斷有兩類：流 中斷和訪問中斷。前者的流是指包到達的輸入流，而後者的流是指與之相連的模塊訪問的輸出

流。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 對於流中斷，該函數確定了包是通過哪個輸入流到達的；而對於訪問中斷，函數可確定所 連處理器或隊列訪問的是哪個輸入流。 4）錯誤 Program Abort：核心函數需要進程上下文。 Recoverable Error：當前事件不是流中斷或訪問中斷。 5）相關函數 採用 op_intrpt_type()確定當前中斷的類型。 採用 op_intrpt_code()確定與當前中斷相關的代碼。 採用 op_intrpt_stat()確定與當前中斷相關的輸入統計索引。 採用 op_pk_send…()和 op_pk_deliver…()將包發送或傳遞到模塊輸入流中。 採用 op_strm_access()訪問處理器或隊列的輸出流。

5. op_intrpt_ici () 該核心函數的作用是獲取與當前中斷相關聯的 ICI。 1）返回值 Ici*——指向與當前中斷相關聯的 ICI 的指針。 2）詳解 進程中斷中攜帶的信息類型包括中斷類型、與中斷相關的標記或代碼，有時還攜帶 ICI 信 息。獲取 ICI 的指針允許接收進程撮其內容。將 ICI 的內容完全處理後，可通過 op_ici_destroy() 重複利用該 ICI。但只有當源進程爲每個輸出中斷創建了新的 ICI，才能銷燬 ICI。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數爲進程提供了一種獲取與當前中斷相關的 ICI 指針的機制。一旦獲取該指針， 便可使用函數 op_ici_attr_get()來提取 ICI 內容。 4）錯誤 該核心函數無錯誤捕獲。 5）相關函數 採用 op_ici_create()創建 ICI。 採用 op_ici_install()爲輸出中斷建立一個 ICI。 採用 op_ici_destroy()解除已處理的 ICI。

採用 op_intrpt_type()確定當前中斷類型。 採用 op_ici_attr_get()獲取 ICI 屬性值。 採用 op_ici_attr_exists()確定 ICI 是否包含特殊屬性。

6. op_intrpt_code () 此核心函數的作用是獲取與調用進程當前中斷相關聯的數值代碼。 1）返回值 int——與當前中斷相關聯的數值代碼。 2）詳解 當在具有與代碼相關聯的中斷之後調用該函數時，將只產生有效值。支持代碼的中斷類型 爲自中斷、進程中斷和遠程中斷。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了一種機制來確定與中斷相關聯的用戶自定義數值代碼，從而確定其目 的，主要用於存在多個相同類型、不同目的的中斷的情況下。 4）錯誤 該核心函數無錯誤捕獲。 5）相關函數 採用 op_intrpt_type()確定當前中斷類型。 採用 op_intrpt_strm()確定與當前中斷相關的流索引。 採用 op_intrpt_stat()確定與統計中斷相關的輸入統計索引。 採用 op_intrpt_source()確定當前中斷的源對象。 採用 op_intrpt_ici()獲取與當前中斷相關的 ICI。

2.10 包函數集 Pk(Packet)函數集是有關處理包、主要數據建模以及封裝機制的核心函數的集合。Pk 函數 集中支持的操作類型包括創建/銷燬包、設置/獲取包的數據內容以及獲取包的特殊屬性的信息。 1. op_pk_create_fmt (format_name) 此核心函數的作用是創建一個具有預定義包格式的包，其參數說明如表 2-26 所示。 表 2-26 參 數 類 型 op_pk_create_fmt()函數的參數說明 描 述

包格式名（名格式是在包格式編輯器中創建的，包格式必須放 format_name const char* 在模型目錄中， 否則將發生錯誤。 包格式文件採用.pk.m 後綴名）

1）返回值 Packet*——指向新創建的包的指針，如果發生可恢復錯誤，則返回 OPC_NIL。 2）詳解 新創建的包由仿真內核分配，並在調用該函數的進程模型所在的處理器或隊列處加入循 環。由於採用預定義的包格式，因而新創建的包的某些字段可能採用預先指定的默認值。包的 初始大小就是所有字段大小的總和，包的 bulk 數據大小與包格式無關，初始值爲零，可通過函 數 op_pk_bulk_size_set()進行修改。 包一旦被創建，將被分配一個惟一的 ID 號。包的創建時間和時間戳均設爲調用該函數時 的仿真時間，而創建模塊和戳模塊設爲運行調用該函數的進程模塊。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數提供了一種獲取具有預定格式和默認內容的格式化億的機制。由於字段的數據 類型不能更改也不能添加新的字段，因而格式化包是面向特定數據集通信的。採用格式化包的 好處就在於其字段可通過名稱來標識，這將簡化設置時的操作。但需注意的是，字段名必須與 預定的包格式中的字段名一致，否則當利用名稱來確定字段時將造成性能的下降。 新創建的包被賦予特定的內容，並使用 op_pk_send…()和 op_pk_deliver…()函數將其從創 建模塊轉發出去，同時將新建包的指針存儲到一個進程模型狀態變量中，以供稍後再次傳輸包 時使用。 4）錯誤 Program Abort：內存分配失敗。 Program Abort：分段錯誤（由錯誤的格式名稱參數引起） 。 Recoverable Error：包格式不可識別。 Recoverable Error：設置了非法包格式字段。不可在創建設置類型結構字段。 Recoverable Error：設置了非法包格式字段。不可在創建設置類型包字段。 5）相關函數 採用 op_pk_nfd_set()設置格式化包的字段。 採用 op_pk_send…()或 op_pk_deliver…()將包發送到其他模塊。 採用 op_pk_destroy()銷燬無用包。

2. op_pk_copy (pkptr) 此核心函數的作用是創建指定包的複本，其參數說明如表 2-27 所示。

表 2-27 op_pk_copy()函數的參數說明

參 數 pkptr 1）返回值

類 型 Packet* 指向原包的指針

描

述

Packet*——指向複本包的指針。 2）詳解 該核心函數創建一個包，並將指定包的頭部複製到新創建的包中。複本包將引用原包的字 段，當原包或複本包的某個字段發生改變時，所有字段的複製必須在改變之前完成。 所有格式化包和非格式化包都可以用用該函數來進行復制，複本包將具有與原包相同的類 型。對結構字段（OPC_FIELD_TYPE_STRUCT）的複製採用與字段分配相關的函數，如函數 op_pk_fd_set()或 op_pk_nfd_set()。對包字段（OPC_FIELD_TYPE_PACKET）的複製將採取包的 遞歸複製。其他字段類型都作爲普通數據項進行復制。 複本包被分配一個惟一的 ID。 包的創建時間設爲調用該函數時的仿真時間， 創建模塊設爲 運行該函數的進程的模塊。若該函數不是由進程或間接進程函數調用的，那麼創建模塊的對象 ID 將設爲常量 OPC_OBJID_INVALID。包的時間戳和模塊是由原包複製而來的，因此戳以複本 包字段爲準，可通過顯式調用 op_pk_stamp()對其進行更改。 在複製過程中，原包的路由也將被複制，但並不複製 ICI，原包和複本包均通過指針指向 同一個 ICI。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數提供了一種複製包的機制，主要用於： ? ? 產生包的多個洪泛傳輸。 備份輸出的包以供將來重傳使用。

4）錯誤 Program Abort：分段錯誤（由無效包指針、畸形包或畸形結構/包字段引起） 。 Program Abort：總線錯誤（由對包的結構字段分配無效地址引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未許可包。 Program Abort：內存分配失敗。 5）相關函數 採用 op_pk_id ()確定複本包的包 ID。 採用 op_pk_destroy()銷燬原包或複本包。 採用 op_pk_create()或 op_create_fmt()創建不基於其他包的新包。

3. op_pk_destroy (pkptr) 此核心函數的作用是銷燬包並釋放其內存資源，其參數說明如表 2-28 所示。 表 2-28 參 數 pkptr 1）返回值 void——無返回值。 2）詳解 當不再使用一個包時，就可以通過該函數將其從循環中移除，釋放其內存，並同時銷燬與 之相關的路由。 在銷燬包時並不同時銷燬與之相關的 ICI， 因爲其他包或進程模型可能仍在使用 該 ICI。可以使用函數 op_ici_destroy()來單獨銷燬 ICI。 包被銷燬後，就可重新利用其釋放的內存來創建新的包。如果操作失敗將導致大量無用數 據包的積聚，若這些無用數據包占用了足夠的虛擬內存，且不再滿足新對象的分配需求，那麼 最終將導致仿真異常中斷。格式化包和非格式化包均可採用該函數來進行銷燬。 該函數會自動釋放所有結構字段和包字段的內存。不過，如果在銷燬前已使用 op_pk_nfd_get()獲取包的結構字段內容， 那麼就必須使用 op_prg_mem_free()釋放結構字段內存。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 ? 該核心函數提供了一種通過銷燬無用包，釋放其內存，來襀內存循環利用的機制。仿 真內核可自由分配釋放後的內存。一旦函數正確返回，被銷燬包的指針就宣告無效。 4）錯誤 Program Abort：分段錯誤（由無效包指針、畸形包或畸形結構/包字段引起） 。 Program Abort：總線錯誤（由對包的結構字段分配無效地址引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未許可包。 Program Abort：包指針指向靜態包。 5）相關函數 採用 op_pk_create()或 op_create_fmt()創建不基於其他包的新包。 採用 op_pk_fd_strip()或 op_pk_nfd_strip()移除包中的某個字段。 採用 op_pk_creation_time_get()確定包被銷燬前的生存時間。 類 型 Packet* 指向需被銷燬的包的指針 op_pk_destroy()函數的參數說明 描 述

4. op_pk_get (instrm_index) 該核心函數的作用是獲取到達輸入包流的包的指針，並將其從流中移除，其參數說明如表 2-29 所示。 表 2-29 op_pk_copy()函數的參數說明 參 數 instrm_index int 1）返回值 Packet*——指向從輸入流包流的指針。如果流中無包，則返回 OPC_NIL。可首先通過函 數 op_strm_empty()來確定流中是否包含包。 2）詳解 該核心函數獲取包的方式有兩種，一種是獲取在包流中發送的包，另一種 是獲取由遠程 模塊傳送的包，兩種獲取方式沒有任何區別。 安靜地發送或傳遞到輸入流（採用函數 op_send_quiet()或 op_deliver_quiet()）中的包不會 引起相關模塊的中斷。如果多個安靜包屬於同一個輸入流，則它們將按到達順序進行排隊，使 用函數 op_pk_get()只獲取輸入流隊列中到達的第一個包，通過連續調用該函數就可從流中獲取 剩餘的包（可調用函數 op_strm_pksize()來獲取輸入流隊列中包的數目） 。 由於該核心函數需要進程上下文，因而只有進程模型或進程模型直接或間接調用的函數才 能調用該函數。所有非格式化或格式化包均可通過該核心函數獲取。 當調用該函數時，若輸入流索引超過已存在輸入流的最大索引，那麼仿真內核將試圖分配 新的輸入流，這樣就可通過包傳遞機制的無限多個輸入流中獲取包。 此外，該核心函數的安全級別爲 MT-safe。 3）目的 該核心函數提供了從所屬模塊獲取包的機制。由於該核心函數是進程獲取並非自己創建或 聲明的包的惟一方法，因此大量的進程模型都會採用該函數。 4）錯誤 Program Abort：核心函數需要進程上下文。 Program Abort： 內存分配失敗。 Recoverable Error：輸入流索引溢出。 5）相關函數 採用 op_pk_nfd_send()通過輸出流 採用 op_pk_nfd_deliver()將包傳遞到未連模塊的輸入流中。 採用 op_pk_send()或 op_pk_deliver()以延時、強制、安靜到達方式傳遞包。 採用 op_strm_empty()或 op_strm_pksize()確定輸入流中是否包含包。 類 型 描 所屬模塊輸入包流的索引。 述

5. op_pk_send (pkptr, outstrm_index) 此核心函數的作用是將包發送到輸入包流中，基於當前仿真時間安排包到達某個目的模塊 的時間，並釋放調用進程對包的所有權，其參數說明如表 2-30 所示。 表 2-30 參 數 pkptr 類 型 Packet* 指向被髮送包的指針 所屬模塊輸出包流的索引值 op_pk_send()函數的參數說明 描 述

outstrm_index int 1）返回值 void——無返回值。 2）詳解

該核心函數函數確定了包到達目的模塊的時間。到達時間是相對於當前仿真時間而設定 的，相應事件隨之加入到仿真事件列表中。事件發生在仿真時間結束之前，但並不在執行當前 仿真時間已經安排的其他事件之前執行。在執行事件之前，將通過一個流中斷來調用目的模塊。 如果目的模塊是一個處理器或隊列，相關進程可通過函數 op_intrpt_type()來確定中斷是否由輸 入流引起，如果是，則可通過函數 op_pk_get()獲取該包。 一旦包傳給該函數，包的所有權即從調用進程轉到目的模塊，之前進程將不能再繼續調用 包。 由於該核心函數需要進程上下文，因而只有進程模型或進程模型直接或間接調用的函數才 能調用該函數。所有非格式化或格式化包均可採用該函數。 此外，該核心函數的安全級別 Forced serialization。 3）目的 該核心函數提供了在節點內的通過包流相連的模塊間傳遞包的機制。該函數是仿真中進行 包傳遞的最基本函數。此類核心函數提供了延時、強制、安靜到達目的模塊等功能。在不依賴 模塊間物理連接的情況下可通過函數 op_pk_deliver()來傳遞包。 函數 op_pk_sent()允許包傳遞到其他在處理器或隊列中運行的進程或發信機模塊中。 4）錯誤 Program Abort：分段錯誤（由無效包指針或畸形包引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 Program Abort：包指針指向靜態包。 Program Abort：在對象或流中傳遞包失敗。

Program Abort：核心函數需要進程上下文。 Recoverable Error：輸出流索引溢出。 Recoverable Error：輸出流索引未被佔用。 5）相關函數 採用 op_pk_send_delayed()發送延時到達的包。 採用 op_pk_send_forced()發送包並立即在目的點進行處理。 採用 op_pk_send_quiet()發送包但不在目的模塊處引起中斷。 採用 op_pk_send_deliver…()將包傳遞到模塊但並不採用包流。 採用 op_pk_get()獲取包的指針。

6. op_pk_send_delayed (pkptr, outstrm_index, delay) 此核心函數的作用是將包發送到輸出包流中，確定附加一段延時後包到達目的模塊的時 間，並釋放調用進程對包的所有權，其參數說明如表 2-31 所示。 表 2-31 參 數 pkptr 類 型 Packet* 指向被髮送包的指針 所屬模塊輸出包流的索引值 op_pk_send()函數的參數說明 描 述

outstrm_index int 1）返回值 void——無返回值。 2）詳解

該核心函數函數確定了包到達目的模塊的時間。到達時間爲當前仿真時間加上一段特定的 延時，同時相應事件加入到仿真事件隊列中。一旦預設了事件，該函數立即將控制權返回給調 用進程。如果沒有其他高優先級的事件，那麼預設事件將在指定的延時後如期執行。在延時期 內，調用進程可脫離延時包，執行任何其他事件。因此該函數可用來模擬與包傳輸相關的時延。 當執行該事件時，目的模塊將會收到流中斷，表示可通過函靈符 op_pk_get()獲取該包。 一旦包傳到該函數，調用進程就不再擁有包的所有權。任何由傳遞包指針的核心函數調用 的發送進程將引起包的所有權錯誤。該核心函數需要進程上下文，可支持格式化包和非格式化 包。 此外，該核心函數的安全級別 Forced serialization。 3）目的 該核心函數提供了通過包流相連的模塊間傳遞包的機制。該函數是 op_pk_send()的衍生函 數， 對於模擬由調用進程引起的處理延時或傳輸延時很有用。op_pk_send()的其他衍生函數提供 了強制、安靜到達目的模塊等功能。在不依賴模塊間物理連接的情況下可通過函數

op_pk_deliver()來傳遞包。 函數 op_pk_send_delayed()允許包傳遞到其他處理器或隊列中運行的進程或發信機模塊中。 4）錯誤 Program Abort：分段錯誤（由無效包指針或畸形包引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 Program Abort：包指針指向靜態包。 Program Abort：在對象或流中傳遞包失敗。 Program Abort：核心函數需要進程上下文。 Recoverable Error：輸出流索引溢出。 Recoverable Error：輸出流索引未被佔用。 Recoverable Error：延時值溢出。 5）相關函數 採用 op_pk_send ()發送無延時的包。 採用 op_pk_send_forced()發送包並立即在目的點進行處理。 採用 op_pk_send_quiet()發送包但不在目的模塊處引起中斷。 採用 op_pk_send_deliver…()將包傳遞到模塊但並不採用包流。 採用 op_pk_get()獲取包的指針。

7. op_pk_nfd_set (pkptr, fd_name, value) 此核心函數的作用是爲給定包的某一字段賦值， 該字段由其名稱確定， 所賦的值只能是 Int、 Double 或包字段，其參數說明如表 2-32 所示。 表 2-32 參 數 pkptr fd_name value 1）返回值 Compcode — — 確 認 賦 值 操 作 是 否 成 功 的 完 成 代 碼 。 如 果 發 生 可 恢 復 錯 誤 ， 則 返 回 OPC_COMPCODE_FAILURE。 2）詳解 函數參數 value 的聲明採用 Vartype，它可接受 int、double 或包指針。核心函數會根據包的 類 型 Packet* const char* Vartype 指向給定包的指針 字段名 所賦的值 op_pk_()函數的參數說明 描 述

內部結構來確定傳遞給確定傳遞給參數的是何種類型的字段，從而改變它的字段分配方法。如 果給定字段之前未被賦值，則新字段的大小仍由包格式決定，並相應增加包總的大小。 對於 int、double 和包指針類型，需要指定字段的值。在該函數將包封裝到字段中後，調用 進程就喪失了對被封裝包的所有權，只有用函數 op_pk_fd_get()（如果爲格式化包，採用函數 op_pk_nfd_get()）對其進行解封裝後，纔可重新使用被封裝包。 包類型字段採用特殊的方法來動態確定其大小。在用包格式編輯器在包格式中定義了這種 類型字段後，字段大小值就記入某數據表中。如果字段值設爲“inherited” ，則字段大小就爲被 封裝包的大小，從而準確模擬了包的總大小。如果某字段大小在表中值小於等於 0，將不考慮 任何被封裝包的大小，從而支持模擬數據壓縮。 此外，該核心函數的安全級別 MT-safe。 3）目的 該核心函數提供了對包中字段賦值的機制。該函數只能對格式化包的字段賦值，否則將出 錯。對於格式化包，只需指定字段的值，而字段的類型和大小可從包格式中自動獲取。 4）錯誤 Program Abort：分段錯誤（由無效包指針或 fd_name 參數引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 Recoverable Error：包中無此字段。 5）相關函數 採用該核心函數的衍生函數來給包的 information 或 structure 字段賦值。 採用 op_pk_fd_set()根據數字索引爲字段賦值。 採用 op_pk_nfd_get()獲取包中某字段的值。 採用 op_pk_nfd_strip()刪除某字段，並相應減小包的總大小。

8. op_pk_nfd_get (pkptr, fd_name, value_ptr) 此核心函數的作用是獲取給定包中某字段值，將字段類型狀態改爲“unset” ，根據名稱來 確定字段，其參數說明如表 2-33 所示。 表 2-32 參 數 pkptr fd_name value_ptr 類 型 Packet* const char* Vartype 指向給定包的指針 字段名 指向存放指定字段地址的指針 op_pk_nfd_get()函數的參數說明 描 述

1）返回值 Compcode — — 確 認 操 作 是 否 成 功 的 代 碼 。 如 果 發 生 錯 誤 ， 則 返 回 OPC_COMPCODE_FAILURE。 2）詳解 該核心函數參數支持五種字段類型：int、double、packet、information 和 structure。對於 簡單的字段類型，如 int 和 double，直接將它們的值賦給參數，並不受該函數影響。 對於 packet 和 structure 字段類型，同樣將它們的值賦給參數。然而，當訪問這些值時，就 將其從包中刪除，其狀態更改爲“unset” ，且不可通過函數 op_pk_nfd_get()來進行訪問，同時包 的總大小也隨之減小。這種機制更嚴格了對被封裝字段內容的所有權控制。 訪問未定義的的 information 字段是非法的，爲了避免產生錯誤，應將字符串“unspecified” 複製到被傳遞值的指針中。 此外，該核心函數的安全級別 MT-safe。 3）目的 該核心函數提供了獲取包字段值的機制，常用於將包作爲用於進程間通信的數據容器。通 常在包到達處理器或隊列輸入流時調用該函數，且必須對該包進行處理、存儲並需要一個應答 信息。 4）錯誤 Program Abort：分段錯誤（由無效包指針或 fd_name 參數引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 5）相關函數 採用 op_pk_fd_set()爲包字段賦值。 採用 op_pk_nfd_get_db1()通過數字索引獲取包中 double 類型字段值。 採用 op_pk_nfd_get_int32()通過數字索引獲取包中 32 位整型字段值。 採用 op_pk_nfd_get_int64()通過數字索引獲取包中 64 位整型字段值。 採用 op_pk_nfd_get_objid()通過數字索引獲取包中對象 ID 字段值。 採用 op_pk_nfd_get_pkid()通過數字索引獲取包中包 ID 字段值。 採用 op_pk_nfd_get_pkt()通過數字索引獲取包中包字段值。 採用 op_pk_nfd_get_ptr()通過數字索引獲取包中指針字段值。 採用 op_pk_fd_get()通過數字索引獲取格式化包或非格式化包中某字段值。 採用 op_pk_nfd_type()確定包字段的類型。 採用 op_pk_nfd_size()確定包字段的大小。

採用 op_pk_nfd_is_set()確定包字段是否已設置。

9. op_pk_creation_time_get (pkptr) 此核心函數的作用是獲取包創建時的仿真時間，其參數說明如表 2-34 所示。 表 2-34 參 數 pkptr 1）返回值 double——給定包創建時的仿真時間。 2）詳解 新包通常通過以下三種方法進入循環： ? ? ? 由函數 op_pk_create()或 op_pk_create_fmt()顯式創建； 通過函數 op_pk_copy()複製已存在的包； 通過核心函數自動複製在總線或無線鏈路上向多個目的地傳輸的包。 類 型 Packet* 指向相關包的指針 op_pk_creation_time_get()函數的參數說明 描 述

通過上述前兩種方法創建的包將被賦予新的創建模塊 ID 和創建時間。若外部進程的上下 文調用第二種方法，此時的創建模塊 ID 將設爲常量 OPC_OBJID_INVALID。通過第三種方法 複製的包將被賦予最初傳送的包的創建信息。 對包的許多操作大多都不會影響包的創建信息。正如前面提到的，在總線和無線鏈路上傳 輸將創建多個包的複本，但但複本都將保留初始的創建信息。通過函數 op_pk_copy()生成的復 本包將產生新的創建信息。 此外，該核心函數可用於格式化包和非格式化包，其安全級別 MT-safe。 3）目的 該核心函數提供了確定包創建時的仿真時間的機制，主要用於計算端到端傳輸和處理延 時。與函數 op_pk_creation_mod_get()結合，op_pk_create_time_get()函數可用於比較不同源位置 的端到端延時。 4）錯誤 Program Abort：分段錯誤（由無效包指針或 fd_name 參數引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 5）相關函數 採用 op_pk_creation_mod_get()獲取包創建處的模塊 ID。 採用 op_pk_stamp()標記包的當前模塊和仿真時間。

採用 op_pk_stamp_mod_get()和 op_pk_stamp_time_get()通過包戳獲取模塊 ID 和仿真時間。

10. op_pk_total_size_get (pkptr) 此核心函數的作用是獲取包的總大小，其參數說明如表 2-35 所示。 表 2-35 參 數 pkptr 1）返回值 OpT_Packet_Size——給定包的總大小（bit 位數） 。 2）詳解 包的總大小爲數據和各個附加字段大小的總和。修改數據大小、設置/復位包字段、修改包 字段大小都可影響包總的大小。 此外，該核心函數可用於格式化包和非格式化包，其安全級別 MT-safe。 3）目的 該核心函數提供了一種確定包總的大小的機制，主要用於統計量收集、資源分配、根據大 小對包進行分類。 4）錯誤 Program Abort：分段錯誤（由無效包指針或 fd_name 參數引起） 。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向未知包。 5）相關函數 採用 op_pk_total_size_set()分配包的總大小。 採用 op_pk_bulk_size_set()設置包的 bulk 數據大小。 採用 op_pk_bulk_size_get()獲取包的 bulk 數據大小。 採用 op_pk_fd_size()修改非格式包中的字段大小。 採用 op_pk_fd_strip()或 op_pk_nfd_strip()刪除某字段從而減小包總的大小。 類 型 Packet* 指向相關包的指針 op_pk_total_size_get()函數的參數說明 描 述

2.11 子隊列函數集 Subq（Subqueue）函數集是與隊列模塊中與單一的隊列資源處理相關的核心函數的集合。

1. op_subq_pk_insert (subq_index, pkptr, pos_index) 此核心函數的作用是將包插入到給定子隊列的指定位置，其參數說明如表 2-36 所示。

表 2-36 參 數 subq_index pkptr pos_index 1）返回值 類 型 int Packet* int

op_subq_pk_insert()函數的參數說明 描 述

給定子隊列的索引（子隊列索引從 0 開始，依次加 1 遞增，無上限） 指向給定包的指針 子隊列中包應插入的位置索引

int——表明插入是否成功的插入代碼。 該返回代碼值包括以下符號常量： OPC_QINS_OK、 OPC_QINS_FAIL、OPC_QINS_PK_ERROR、OPC_QINS_SEL_ERROR。 2）詳解 如果位置索引小於零或不是系統支持的符號常量（OPC_QPOS_PRID、OPC_QPOS_HEAD 或 OPC_QPOS_TAIL） ，那麼該函數將把包插入到子隊列的隊列頭。同樣，如果位置索引大於等 於子隊列中包的總數，那麼該函數將把包插入到子隊列的隊列尾。 又若位置索引爲 OPC_QPOS_PRID，函數將根據包的優先級對其進行插入。優先級越高的 包越靠近隊列頭，沒有指定優先級（OPC_PRiO_NOT_SET）的包將被插入到最後。如果子隊列 中存在一個或多個具有相同優先級的包，則新包將立即被插入到它們後面。 注意： 當採用 OPC_QPOS_PRID 插入包時，必須首先使用函數 op_subq_sort()對子隊列進行 優先級排序。 子隊列初始化爲空，可通過函數 op_subq_pk_insert()將包插入到子隊列中，通過函數 op_subq_pk_remove()、op_subq_flush()或 op_q_flush()將包從子隊列中移除。由於子隊列容量有 限，插入包操作可能失敗，幫此時進程將對包進行靈活處理（如銷燬、回送到源等） ，包狀態不 會受到影響。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數提供了惟一一種將包插入到子隊列中的方法。位置索引參數可以靈活地確定給 定包插入的位置，既可以是具體的數值，也可以是包的優先級。 4）錯誤 Program Abort：核心函數需要隊列上下文。 Program Abort：包指針爲空。 Program Abort：包指針指向已銷燬包。 Program Abort：包指針指向靜態包。 Program Abort：分段錯誤（由畸形包引起） 。 Recoverable Error：子隊列選擇標記不可識別（此時返回 OPC_QINS_SEL_ERROR） 。 Recoverable Error：包已插入到子隊列中（引時返回 OPC_QINS_PK_ERROR） 。

注意：如果由於隊列或子隊列的容量不夠而引起的包插入失敗，將返回常量 OPC_QINS_FAIL，但這不屬於錯誤。 5）相關函數 採用 op_subq_pk_access()獲取包在子隊列中的指針，但關不將包從子隊列中移除。 採用 op_subq_pk_remove()將包從子隊列中移除，並獲取其指針。 採用 op_subq_pk_swap()交換兩個包在子隊列中的位置。 採用 op_subq_flush()移除子隊列中所有的包。

2. op_subq_pk_remove (subq_index, subq_index) 此核心函數的作用是獲取包在子隊列中的位置指針，並將其從子隊列中移除，其參數說明 如表 2-37 所示。 表 2-37 參 數 subq_index subq_index 1）返回值 Packet*——從給定子隊列中移除的包的指針，如果發生可恢復錯誤，則返回 OPC_NIL。 2）詳解 只能在隊列模塊中運行的進程上下文中調用該核心函數（或由隊列進程調用的函數調用） ， 如果處理器或管道階段運行的進程調用該函數，那麼將發行錯誤。 如果位置索引爲負值，或大於等於隊列中包的數目，那麼將產生可恢復錯誤並返回常量 OPC_NIL。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 提供了惟一一種將包非破壞性地從子隊列中移除的機制。 通過其他函數， op_subq_flush() 如 和 op_q_flush()也可將包從子隊列中移除。位置索引參數可靈活地確定哪個包將被移除，它可以 是一個具體的數值， 也可以由包的優先級確定，此進高優先級的包無論在哪個位置都將被移除。 4）錯誤 Program Abort：核心函數需要上下文。 Recoverable Error：子隊列選擇標記不可識別。 Recoverable Error：位置索引超出子隊列範圍。 5）相關函數 類 型 int int 相關子隊列的索引 子隊列中需移除的包所在位置的索引（隊列頭的位置索引爲 0，依 次加 1 遞增，直到隊列尾） op_subq_pk_remove()函數的參數說明 描 述

採用 op_subq_pk_access()獲取包在子隊列中的指針，但關不將包從子隊列中移除。 採用 op_subq_pk_insert()將包插入到子隊列中。 採用 op_subq_pk_swap()交換兩個包在子隊列中的位置。 採用 op_subq_flush()移除子隊列中所有的包。

2.12 統計量函數集 Stat（Statistic）函數集中所包含的核心函數將用戶自定義的自動計算的統計量寫入仿真中 創建的數據文件。輸出文件共有兩類：矢量輸出文件和標量輸出文件。 1. op_stat_reg (group_dot_stat_name, stat_index, type ) 此核心函數的作用是返回進程模型中節點或模塊統計量（局部或全局）的句柄，其參數說 明如表 2-38 所示。 表 2-38 參 數 類 型 op_stat_reg()函數的參數說明 描 述

group_dot_stat_name const char* stat_index int

統計量的所在組和名稱，用“． ”隔開 統計量的數字索引，若爲一維統計量， 則爲 OPC_STAT_INDEX_NONE OPC_STAT_GLOBAL（全局統計量）

type 1）返回值

int OPC_STAT_LOCAL（局部統計量）

Stathandle——統計量句柄，可在函數 op_stat_write()和 op_stat_write_t()調用時使用。 2）詳解 該函數與 op_stat_obj_reg()類似，但本函數只能用在進程模塊上下文中，且既可註冊局部 統計量，又可註冊全書統計量。 仿真內核集中管理全書統計量和局部統計量， 爲每個統計量都保存了所屬組、 名稱、 索引、 類型和輸出矢量。當使用函數 op_stat _reg()註冊統計量時，可爲其指定前面四項。如果能做到 名稱同步，則可允許多個進程訪問相同的統計量。所有進程都可集結同一全局統計量，而同一 模塊的進程纔可集結同一局部統計量。 多維統計量提供了一個輸出統計量庫，Stathandle 根據索引指向庫中的元素。一維統計量 全用符號常量 OPC_STAT_INDEX_NONE 作爲索引值。 使用全書統計量時， 模型中的所有進程共享一個輸出矢量， 並記錄它們測量的端到端延時。 而使用局部統計量時，每個進程只記錄自己的輸出矢量。 註冊統計量時將會在現有統計量中搜索名稱和所屬組。爲提高效率，一個統計量只能註冊 一次，然後緩存統計量句柄以便使用。

此外，該核心函數的安全級別爲 Forced serialization。 3）目的 統計量註冊提供了一種多個進程共享輸出矢量的機制。進程只需要調整統計量名稱就可通 過註冊來訪問統計量，這可以比較容易地避免獨立模型間的衝突。函數 op_stat_write()和 op_stat_write_t()可以根據該函數返回的統計量句柄，並將值寫到統計量中。 4）錯誤 Program Abort：分段錯誤（由無效或畸形 stat_name 參數引起） 。 Recoverable Error：無法註冊統計量（由未聲明統計量引起） 。 Recoverable Error：因內存限制而無法註冊統計量。 Program Abort：核心函數需要進程上下文。 Recoverable Error：統計量索引溢出。 5）相關函數 採用 op_stat_obj_reg()訪問任意鏈路、路徑、模塊或子模塊對象統計量。 採用 op_stat_write()將值寫到輸出統計量中，並標記當前仿真時間。 採用 op_stat_write_t()將值寫到輸出統計量中，並標記指定的仿真時間。 採用 op_stat_scalar_write() 將值寫到與其他仿真中記錄的標量合併的標題統計量中。

2. op_stat_write (stat_handle, value) 此核心函數的作用是將（時間，值）對寫到指定統計量中，將寫入的值通過參數傳遞給該 函數，時間爲當前仿真時間，其參數說明如表 2-39 所示。 表 2-39 op_stat_write()函數的參數說明 參 數 stat_handle value 1）返回值 void——無返回值。 2）詳解 該核心函數爲給定統計量的輸出矢量附加一個新的（時間，值）對。統計量只能是採用函 數 op_stat_reg()註冊的統計量。句柄使用不當將導致可恢復仿真錯誤。 仿真模型中的不同進程如果使用相同的統計量句柄，那麼就可通過該函數將值寫到同一個 輸出矢量中。 在同一仿真時間對函數 op_stat_write()的多次調用將按序記錄，而不是互相覆蓋。 爲了在輸出矢量文件中產生數據，統計量必須使用探針編輯器中定義的探針對象探測，或 類 型 Stathandle double 指定統計量的統計量句柄 指定統計量將寫入的值 描 述

在項目編輯器中通過選擇統計量操作將其選中。探針文件的名稱由仿真的探針屬性確定。需要 設置仿真的 record_gstats 屬性來記錄所有的全書統計量。 如果捕獲模式是“divides by time” ，且在特定時間段內統計量有效，則必須採用函數 op_stat_write()在時間段結束時向統計量寫入零值，以報告系統該時間段已結束。 此外，該核心函數的安全級別爲 Forced serialization。 3）目的 該核心函數將值寫入輸出矢量中，並標記當前仿真時間。 如果 Stathandle 指向一個與統計線相連的局部統計量，且該統計線處於解狀態，那麼將爲 統計線的目的模塊預設一箇中斷。 4）錯誤 Program Abort：分段錯誤（由無效統計量句柄引起） 。 Recoverable Error：使用未註冊的統計量句柄。 5）相關函數 採用 op_stat_local_read()讀取輸入統計量的當前值。 採用 op_stat_write_t()將值寫到輸出統計量中，並標記指定的仿真時間。 採用 op_stat_scalar_write() 將值寫到與其他仿真中記錄的標量合併的標題統計量中。 採用 op_stat_obj_reg()訪問任意鏈路、路徑、模塊或子模塊對象統計量。 採用 op_stat_reg()獲取統計量句柄。