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