FAST軟件編程基礎(chǔ)（2）FAST編程API
發(fā)布時間：2019-04-19
FAST編程庫Libua.a和linreg.a為Fast軟件編程提供標(biāo)準(zhǔn)編程API。Fast編程API主要分為三類。一是用戶UA編程API，用戶可在UA進(jìn)程中直接調(diào)用這些API函數(shù)實(shí)現(xiàn)與FAST平臺的通信，包含UA管理、分組收發(fā)和FAST流水線管理三類；二是Fast平臺管理API，實(shí)現(xiàn)對Fast硬件平臺中FPGA OS的管理；三是擴(kuò)展API，即面向FAST流水線中特定硬件模塊特定功能而設(shè)計的API。
一、UA編程API
UA編程使用的基本API如下表所示。如果用戶沒有向硬件流水線中添加自定義的模塊，那么用戶UA只使用以下6個函數(shù)就可以實(shí)現(xiàn)與Fast平臺的交互。如果用戶向Fast流水線中添加了定制的模塊，則需要根據(jù)所添加硬件模塊的功能對編程API進(jìn)行擴(kuò)充。
為了簡化UA對硬件流水線模塊的管理，F(xiàn)ast編程API提供了讀寫硬件模塊的函數(shù)。在Fast編程庫函數(shù)實(shí)現(xiàn)時，上述讀寫函數(shù)均被轉(zhuǎn)換成控制類的Fast分組發(fā)往硬件流水線，并通過流水線的Cin/Cout控制環(huán)操作實(shí)現(xiàn)對分組的讀寫。
上表中的6個API函數(shù)的原型和參數(shù)說明如下。
（1）int fast_ua_init(int mid, fast_ua_recv_callbackcallback);
輸入?yún)?shù)mid為用戶為UA設(shè)置的模塊號，該模塊號是FAST平臺對軟硬件模塊的唯一標(biāo)識。根據(jù)FAST規(guī)范，軟件UA的mid范圍是128-255，由于128默認(rèn)為內(nèi)核協(xié)議棧，因此用戶UA的mid范圍可設(shè)置為129-255。用戶需保證mid參數(shù)不與系統(tǒng)中其他UA的參數(shù)沖突，如果發(fā)生沖突，函數(shù)返回值為1，表明注冊失敗。輸入?yún)?shù)callback為Fast平臺在接收到發(fā)往用戶UA的分組時的回調(diào)函數(shù)，用戶需要在程序中對callback函數(shù)進(jìn)行定義。如果UA注冊成功，函數(shù)返回值為0，否則返回非0值。
（2）void fast_ua_destroy(void);
用戶UA在退出時需執(zhí)行的操作，主要是通知FAST平臺釋放向UA分配的mid編號。
（3）int fast_ua_send(struct fast_packet *pkt,int pkt_len)；
用戶UA調(diào)用該函數(shù)向Fast平臺發(fā)送分組。其中pkt是指向fast_packet數(shù)據(jù)結(jié)構(gòu)的指針。該數(shù)據(jù)結(jié)構(gòu)包含了指向分組緩沖區(qū)的指針以及分組的目的mid等參數(shù)。執(zhí)行成功返回報文長度，執(zhí)行失敗返回-1。用戶在調(diào)用該函數(shù)時，需要注意以下兩點(diǎn)。一是如果UA想直接將分組從Fast平臺的網(wǎng)絡(luò)接口發(fā)出，需要將dmid設(shè)置為5，即將目的模塊設(shè)置為Fast硬件流水線中的通用輸出模塊（GOE），同時設(shè)置Outport和Outtype字段，指明輸出的類型（單播/組播/廣播）以及輸出端口號或組播ID；二是如果UA想將分組發(fā)送給其他的UA，則需要將dmid設(shè)置為UA的mid編號。一個用戶UA如何獲取其他UA的mid不是Fast規(guī)范考慮的問題。
（4）void fast_ua_recv()；
UA啟動接收FAST報文。每當(dāng)Fast內(nèi)核接收到目的mid為用戶UAmid的分組后，會通過Netlink機(jī)制將分組拷貝到用戶空間，并調(diào)用UA初始化時設(shè)置好的callback回調(diào)函數(shù)對報文進(jìn)行處理。
（5）u32 fast_ua_hw_rd(u8 dmid, u32addr, u32 mask);
其中dmid為讀操作的硬件流水線模塊號，addr為模塊內(nèi)部的讀地址偏移量。mask為讀數(shù)據(jù)的掩碼，目前未使用，用戶應(yīng)將mask設(shè)置為0。
（6）void fast_ua_hw_wr(u8dmid,u32 addr,u32 value,u32 mask);
其中dmid為寫操作的硬件流水線模塊號，addr為模塊內(nèi)部的寫地址偏移量，value為寫數(shù)據(jù)的值。mask為寫數(shù)據(jù)的掩碼，目前未使用，用戶需設(shè)置為0。
三、擴(kuò)展API
根據(jù)Fast流水線的規(guī)范，用戶可以根據(jù)分組處理的需求對Fast硬件流水線中的模塊進(jìn)行擴(kuò)展和定制。因此對于不同硬件流水線模塊也會產(chǎn)生不同的擴(kuò)展API。
典型的例子是基于Fast的SDN交換實(shí)現(xiàn)中，硬件流水線包含了GPP，GKE，GME，GAC和GOE5個功能模塊。用戶UA可能需要對這些功能模塊進(jìn)行管理。例如配置GME模塊的規(guī)則表和GAC模塊中的動作表等。雖然規(guī)則表和動作表在模塊中具有固定的偏移地址，UA可使用fast_ua_hw_rd()和fast_ua_hw_wr()函數(shù)對其管理，但這樣十分復(fù)雜。為此，可基于基礎(chǔ)的fast_ua_hw_rd()和fast_ua_hw_wr()函數(shù)，再封裝成fast_rule_add()和fast_rule_del()等擴(kuò)展的API，簡化用戶UA編程的復(fù)雜性。
關(guān)于Fast通用模塊的擴(kuò)展API我們將在后續(xù)文章中介紹。
