DSP TMS320C6455 芯片支持库CSL API参考
本文翻譯自官方庫《C6455_CSL_APIREFERENCE》。
1 CSL介紹
芯片支持庫由一系列定義良好的API構成，這些API提取出了Soc設備的細節(jié)以便用戶可以配置、控制和讀寫外設，而不用擔心寄存器字段級的實現(xiàn)細節(jié)。
CSL服務以模塊的形式展現(xiàn)。CSL API遵循統(tǒng)一的風格，統(tǒng)一的跨處理器指令集架構，且獨立于操作系統(tǒng)，提高了可移植性。
2 CSL概要
CSL有2層實現(xiàn)，基本寄存器層和更抽象的函數(shù)層。寄存器層包括基本的宏和類型定義。函數(shù)層由C函數(shù)組成，相對寄存器層更抽象，但同樣實現(xiàn)對底層硬件的控制。
CSL不會管理基礎硬件上的數(shù)據(jù)移動，這些功能是設備驅(qū)動驅(qū)動程序要干的事（程序員實現(xiàn)），CSL盡量不去模糊設備驅(qū)動程序和CSL服務直接的邊界。
CSL以模塊形式提供服務，每個模塊均有2個抽象層（寄存器層、函數(shù)層）。模塊的API是正交的（一個模塊的API不會調(diào)用另一個模塊的API），并且不會從內(nèi)部動態(tài)分配內(nèi)存。這樣對于保持CSL的可擴展性很重要。
3 CSL接口
CSL將每個外設構建一個模塊。
寄存器層頭文件命名:CSLR_.h
函數(shù)層頭文件命名：CSL_.h
為了外設的模塊化，CSL提供了一些芯片級的模塊來實現(xiàn)系統(tǒng)和設備級服務。
| CHIP | 包含了通用的設備說明信息，如寄存器ID，字段定義，寄存器讀和寫功能 |
| VERSION | 提供了版本管理，如chip ID和version ID |
| INTC | 中斷模塊提供中斷管理服務和調(diào)度，該模塊是一個單獨的模塊 |
4 函數(shù)層
CSL提供的函數(shù)層是CSL 3.x風格和CSL 2.x風格的混合體。為了將來利用硬件抽象層并保持最大的兼容性，CSL建議用戶使用函數(shù)層API。
CSL 3.x在所有模塊中都支持一組核心的函數(shù)層API。
| CLS_Init() | 外設初始化函數(shù)，可選用，對外設不起作用 |
| CLS_Open() | 返回一個外設實例的句柄 |
| CLS_Close() | 釋放外設實例的句柄 |
| CLS_HwSetup() | 使用傳進去的CSL_HwSetup結構體配置外設所有的寄存器 |
| CLS_GetHwStatus() | 使用CSL_GetHwSetup結構體查詢當前的外設配置 |
| CLS_HwControl() | 通過傳遞的命令參數(shù)修改一個或多個參數(shù) |
| CLS_HwSetupRaw() | 用傳進去的Config結構體的寄存器值初始化設備寄存器 |
| CLS_Read() | IO外設的讀數(shù)據(jù) |
| CLS_Write() | IO設備的寫數(shù)據(jù) |
另外，還有一些為外設實現(xiàn)特殊的API來執(zhí)行特定的操作。 例如，DMAX模塊的“ CSL_dmaxGetNextFreeParamEntry”API在資源表中搜索下一個空閑參數(shù)入口。
該層導出的函數(shù)是“運行即完成”，意思是它們不應支持異步行為或延遲完成（個人理解：運行完，對外設的操作也就完成了）。
如果外設能啟動事務并通過指定的CPU中斷在以后的某個時間點判斷其完成的能力，則這個過程應由高級軟件（通常是設備驅(qū)動程序）完成，不應在函數(shù)層實現(xiàn)。 通常，CSLAPI不執(zhí)行資源管理或內(nèi)存分配，這應由應用程序代碼或設備驅(qū)動程序管理。
4.1 CSL基本數(shù)據(jù)類型
| Bool | Unsigned short |
| Int | int |
| Char | char |
| String | char * |
| Ptr | void * |
| Uint32 | unsigned int |
| Uint16 | unsigned short |
| Uint8 | unsigned char |
| Int32 | int |
| Int16 | short |
| Int8 | char |
| CSL_BitMask8 | Uint8 |
| CSL_BitMask16 | Uint16 |
| CSL_BitMask32 | Uint32 |
| CSL_Reg8 | volatile Uint8 |
| CSL_Reg16 | volatile Uint16 |
| CSL_Reg32 | volatile Uint32 |
| CSL_Status | Int16 |
4.2 函數(shù)層命名約定
CSL命名分為2種，需聲明的名稱（如函數(shù)、常量）及符號常量或宏（通過enum或#define定義），需聲明的名稱要避免用戶重定義，盡快可以#define重定義，但不推薦，因為一旦發(fā)生沖突，后果不可預測。
4.2.1 CSL 3.x命名約定
| CSL__ | 指定為#define或枚舉的符號常量。 整個名稱必須使用大寫字母，表示外設名稱，而表示任何名稱，代表指定或定義的項目。 部分可以嵌入一個或多個下劃線，以提高可讀性。 | CSL_INTC_EVENTID_CNT |
| CSL_ | 外設模塊類型。 CSL_前綴將大寫。 模塊名稱字符串大寫，并遵循標題大小寫約定，沒有任何下劃線。大寫字母用于表示新單詞或短語的開頭。 | CSL_TimerObj CSL_IntcEventId CSL_I2cHwSetup CSL_I2cHandle |
4.2.2 CSL 2.x命名約定
| _ | 指定為#define或枚舉的符號常量。 整個名稱必須使用大寫字母，表示外設名稱，而表示任何名稱，代表指定或定義的項目。 部分可以嵌入一個或多個下劃線，以提高可讀性。 | MCBSP_RCV_START |
| _ | 外設模塊類型。 模塊名稱前綴字符串大寫，名稱部分首字母大寫后面小寫，沒有任何下劃線。大寫字母用于表示新單詞或短語的開頭。 | **MCBSP_Obj |
| HPI_Config ** |
4.3 符號常量
| CSL___REGS | 外設模塊第n個實例的基地址，如CSL_TIMER_1_REGS |
| CSL__CHA_REGS | 對支持多通道外設的通道n的硬件基地址 |
4.4 錯誤代碼
CSL 3.x擴展了錯誤處理支持，通過API的返回值和/或傳遞給調(diào)用本身的狀態(tài)參數(shù)來報告API的成功或失敗。
錯誤代碼是16位帶符號的二進制數(shù)，可以表示32k個唯一的錯誤。錯誤碼分為1024組，每組大小為32，第一組保留用于CSL通用系統(tǒng)錯誤，第二到最后一組分配到各個模塊之間。
正數(shù)為CSL API的正常狀態(tài)/成功運行，負數(shù)為錯誤狀態(tài)。
| CSL_SOK | +1 | 成功 |
| CSL_ESYS_FAIL | -1 | 失敗 |
| CSL_ESYS_INUSE | -2 | 外設資源已被使用 |
| CSL_ESYS_XIO | -3 | 共享IO引腳沖突 |
| CSL_ESYS_OVFL | -4 | CSL系統(tǒng)院溢出 |
| CSL_ESYS_BADHANDLE | -5 | 傳遞給CSL的句柄無效 |
| CSL_ESYS_INVPARAMS | -6 | 無效參數(shù) |
| CSL_ESYS_INVCMD | -7 | 傳遞給CSL的命令無效 |
| CSL_ESYS_INVQUERY | -8 | 傳遞給CSL的查詢無效 |
| CSL_ESYS_NOTSUPPORTED | -9 | CSL不支持的行為 |
5 寄存器層
5.1 寄存器命名規(guī)范
| CSL Module Identifiers | CSL__ID，如CSL_TIMER_ID,CLS_MCBSP_ID |
| Peripheral Instance Identifiers | 如果CSL模塊有不止一個實例，則遵循CSL_<NUM>，如CSL_TIMER_1,CSL_MCBSP_1;如果CSL模塊只有一個實例，則遵循CSL，如CSL_EDMA3,CSL_GPIO |
| Peripheral Instance Count Identifiers | CSL__CNT，如CSL_EMIFA_CNT |
| Peripheral Register Identifiers | _，名字使用指定外設實例掩碼 |
| Peripheral Register Continuous Bit-field Identifiers | ，名字為實例相關的。如TIMER_CNTL_CLKEN |
| Peripheral Register Bit_field Sysbols | _，名字是實例相關的，如CMPAC_TX_CONTROL_EN_RESETVAL |
5.2 外設掩碼結構
Soc 外設通常是通過對外設IO地址空間中的一個或多個寄存器進行讀/寫來編程的。 為了干凈直觀地訪問給定外設實例的所有寄存器，CSL實現(xiàn)了一種稱為**寄存器覆蓋結構（我個人理解：翻譯為掩碼比較合適，故都用掩碼來表示）**的技術。 按出現(xiàn)順序用每個寄存器對應的結構成員來定義C數(shù)據(jù)結構模板，成員類型根據(jù)寄存器的寬度確定，并且 引入適當填充來對齊數(shù)據(jù)結構，以便“ C”對這些寄存器進行正確的尋址。 結構成員與datasheet中的規(guī)定得名稱一樣，以簡化編程。 由于C結構格式定義良好，因此可以在IDE監(jiān)視窗口中查看寄存器，并可以在鍵入時這些寄存器可以智能推測補充完成。
應當注意的是，寄存器掩碼不會實例化，因此也不會占用內(nèi)存。 這些結構的目的主要是便于使用“ C”指針。
例子：
下表展示了TIMER外設的布局，假設有2個實例，一個地址為0x02940000，并且另一個在地址0x02980000，寄存器掩碼如下：
5.3 寄存器層符號常量
CSL寄存器層文件（cslr_.h）定義每個外設寄存器/位字段的標準符號常量，這些符號常量按照如下約定來定義：
CSL__，（對于SYMBOL定義了可選的符號常量如STOP/START）
其內(nèi)存映射的外設采用“本地字節(jié)序”格式，即可以用于CPU解釋。如果CPU和內(nèi)存映射的外圍設備之間的字節(jié)序不匹配，則必須在應用此文件中顯示的_MASK，_SHIFT等符號之前，在外部進行必要的更正（交換）。
5.4 寄存器宏
| CSL_FMK(field, val) | 創(chuàng)建一個將值（val）移動到指定字段位置的AND掩碼。 |
| CSL_FMKT(field, token) | 與CSL_FMK相同，但允許將預定義的符號標記當值使用。 |
| CSL_FMKR(msb, lsb, val) | 與CSL_FMK相同，但允許原始位位置（msb：lsb）指定位字段。 |
| CSL_FEXT(reg, field) | 評估從指定字段收集的位的算術值。 |
| CSL_FEXTR(reg, msb, lsb) | 與CSL_FEXT相同，但允許原始位位置（msb：lsb）指定位字段。 |
| CSL_FINS(reg, field, val) | 將指定值（val）插入寄存器的指定字段中。 |
| CSL_FINST(reg, field, token) | 與CSL_FINS相同，但允許將預定義的符號標記用作值。 |
| CSL_FINSR(reg, msb, lsb, val) | 與CSL_FINS相同，但允許原始位位置（msb：lsb）指定位字段。 |
6 C++兼容性
CSL函數(shù)層大部分是用C實現(xiàn)的，小部分用的匯編（C比較難實現(xiàn)）。此外，API也適當?shù)穆暶鳛榭梢杂肅++實現(xiàn)，但不像C++函數(shù)，CSL API不支持傳遞默認值。
同樣，在CSL API語義要求用戶指定函數(shù)指針的地方，CSL3.x設計不允許用戶輸入C ++函數(shù)指針。 要解決以上限制，用戶需要編寫C語言中的封裝函數(shù)，以封裝C ++成員函數(shù)。該函數(shù)可以設計為將類實例作為參數(shù)輸入（連同其所需的任何其他參數(shù)），并在內(nèi)部調(diào)用適當?shù)念惓蓡T函數(shù)以實現(xiàn)所需的目標。
7 中斷軟件架構
CSL3.x中的INTC模塊旨在為所有基本的中斷控制器功能提供抽象，例如啟用和禁用中斷，指定響應中斷而調(diào)用的用戶功能以及設置所需的硬件屬性。 這些功能并非特定于任何給定的外圍設備。 換句話說，INTC模塊提取處理器提供的通用中斷能力。
注意：CSL 3.0 INTC模塊為一個單獨的塊，作為其余CSL模塊的單獨庫提供。 當使用包含中斷控制器/調(diào)度程序支持的嵌入式操作系統(tǒng)時，不要連接INTC庫。 DSP / BIOS用戶應使用DSP / BIOS v5.21或更高版本支持的HWI（硬件中斷）和ECM（事件組合管理器）模塊。
下面以C6482為例介紹CSL INTC功能。
7.1 中斷控制器
下圖顯示了在虛線邊界內(nèi)的多級中斷控制器。 Level-0控制器是CPU本身的一部分。 此級別為處理器實現(xiàn)主要的中斷向量表。 其余的控制器有助于擴展這些向量，以處理更多的硬件事件。 這些事件，如箭頭所示，可能是通過設備輸入引腳的外部觸發(fā)和/或由片上外設的內(nèi)部斷言。 用cross-hatched boxes表示的外設本身可能是事件控制器（方格），該事件控制器有助于將硬件事件映射到的輸出線來判斷CPU中斷。 每個中斷控制器都將具有可編程控制寄存器，以使能或失能中斷。 控制器還允許用戶將中斷捕獲電路配置為指定的極性，邊沿靈敏度，優(yōu)先級等。級別0中斷控制器具有選擇器功能，可將給定的CPU中斷向量映射為1 -N輸入硬件事件。 盡管該方案在當今的TI處理器中可用于Level-0，但在技術上也可以在其他級別使用。中斷控制器也可能包含多個邏輯塊。 （請參見圖中的2.0、2.1塊。）中斷控制器Level-0到Level-N的所有塊都是CSL3.x中INTC模塊的一部分（由虛線限制）。 用戶只會看到頂級的INTC抽象。 內(nèi)部INTC0至INTCn對用戶隱藏。 各個INTC子塊之間的連接應在INTC模塊初始化和調(diào)度程序設置期間完成，如本文檔隨后的小節(jié)中所述。 重要的是要注意，任何嵌入特定外設（例如C64x EDMA控制器）中的“custom controllers”（請參見圖中的方格框）均不視為INTC功能的一部分。
7.3 INTC模塊初始化
INTC模塊維護一個位掩碼數(shù)組，這些掩碼使INTC能夠跟蹤應用程序正在激活或正在使用的中斷。 每個位的位置對應于一個可以由INTC處理的硬件事件。 總數(shù)位的位置對應于INTC在任何給定時間可以識別和處理的硬件事件的最大數(shù)量。
在level-0處，這對應于CPU主中斷向量。 在其他級別，它對應于控制器中實現(xiàn)的扇入功能和優(yōu)先級解析。 INTC模塊將為每個硬件事件分配唯一的ID，并了解適用于每個級別的此類ID的范圍（即INTC0至INTCn）。
在CSL初始化階段，將調(diào)用INTC模塊初始化函數(shù)CSL_intcInit（）。這會將全局變量CSL_IntcContext.eventAllocMask []重置為零。 這意味著所有中斷都可使用。 該數(shù)組負責解決同一中斷資源上的所有沖突。 每個中斷只能插入一個中斷服務程序。 因此，當在不同事件之間共享同一中斷線時，必須在應用程序中注意事件的同步，并且必須在ISR中識別導致中斷的事件以執(zhí)行適當?shù)墓δ堋?/p>
7.4 中斷調(diào)用說明
成功初始化INTC模塊之后（通過CSL_intcInit（）），用戶可以選擇通過調(diào)用CSL_intcDispatcherInit（）來初始化INTC內(nèi)置調(diào)度程序。 為CSL_intcDispatcherInit（））傳遞的調(diào)度程序記錄參數(shù)用作ISR在特定時間點掛接到特定CPU中斷的記錄。 一旦創(chuàng)建了調(diào)度程序記錄并對其進行了初始化，CSL_plugEventHandler（）將在內(nèi)部執(zhí)行將ISR記錄在調(diào)度程序記錄中，并在中斷向量表中連接相應的主ISR。
通常，當操作系統(tǒng)（OS）運行時，主中斷向量表在OS Scheduler的控制下。 OS Scheduler將在level-0上鉤上其自己的調(diào)度函數(shù)。OS端口可以選擇完全取消CSL調(diào)度程序，也可以選擇自己所需的級別。 他們可以選擇首先初始化CSL中斷調(diào)用器，然后以所需的級別和/或向量槽交換自己的中斷處理程序。 當與CSL一起使用的OS端口使用其自己的調(diào)度程序時，CSL_IntcContext.flags必須等于CSL_INTC_CONTEXT_DISABLECOREVECTORWRITES。 CSL調(diào)度代碼/數(shù)據(jù)可能根本不加載，或者為了優(yōu)化內(nèi)存占用而被覆蓋。 通常，事件分發(fā)記錄構成上下文信息。 該表將保存事件處理程序函數(shù)的地址以及指向要作為單獨參數(shù)傳遞給事件處理程序的任意數(shù)據(jù)對象（void *）的指針。
當不使用INTC分派器時，可以使用CSL_intcHookIsr（）在中斷向量表中掛鉤正確的提取數(shù)據(jù)包，從而在發(fā)生中斷時將CPU控制引向正確的ISR。
7.4 INTC API調(diào)用順序
INTC用戶調(diào)用順序如下：
// Initialize other required CSL3.x Peripherals CSL_intcSetVectorPtr(DEST_ADDR); //If relocation of interrupt vector //required. DEST_ADDR is new location CSL_intcInit(); // INTC Module Initialize CSL_intcDispatcherInit(); // Dispatcher Initialize (if reqd.) CSL_intcGlobalDisable(..); // Disable global interrupts. handle = CSL_intcOpen(..); // Ready an interrupt for use CSL_intcHwSetup(handle..); // Setup interrupt attributes CSL_intcPlugEventHandler(..); // Bind the interrupt with the // corresponding ISR. CSL_intcHwControl(handle..); // assorted control, ex: ISR hookup CSL_intcEventEnable(..); // Enables the event of interest. CSL_intcGlobalEnable(..); // Enable global interrupts. : CSL_intcClose(handle); // End of interrupt use // Terminate Program歡迎關注我的公眾號：槑槑的技術棧。前面兩個字念meimei，二聲，哈哈。
總結
以上是生活随笔為你收集整理的DSP TMS320C6455 芯片支持库CSL API参考的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 属性管理器没有Microsoft.Cpp
- 下一篇： 架构 理论 定律 总结