RT-Thread今天的快速發(fā)展和所取得成績，離不開所有開發(fā)者的持續(xù)貢獻(xiàn)和社區(qū)小伙伴的竭力支持。

一、前言

今年6月，我在一款智能混合型的FPGA芯片上，完成了RT-Thread的移植，并向RT-Thread提交了一個(gè)完整的BSP，后續(xù)又根據(jù)審查意見進(jìn)行了一些完善，最近（11.18）被合并到RT-Thread主分支上。

如果你曾經(jīng)下載過RT-Thread的源碼倉庫，在最常用的STM32 BSP上面的smartfusion2，這個(gè)BSP就是我提交的了，如果有讀者朋友使用過這款芯片，歡迎體驗(yàn)，或者提交BUG。

有的朋友可能注意到了，我這里使用的是FPGA芯片，F(xiàn)PGA芯片還能運(yùn)行RT-Thread嗎？準(zhǔn)備的說，應(yīng)該是FPGA片上的處理器可以運(yùn)行RTOS，這里的處理器，從實(shí)現(xiàn)方式來看，包括硬核和軟核處理器；從內(nèi)核種類上來看，包括ARM核或其他內(nèi)核，如ARM硬核，Altera的NIOS軟盒，Xilinx的microblaze軟核，還有51軟核等，關(guān)于FPGA片上處理器，可以參考以下文章：

• FPGA硬核和軟核處理器的區(qū)別

• 除了ZYNQ還有哪些內(nèi)嵌ARM硬核的FPGA？

此次提交的這個(gè)BSP是我第一次向開源項(xiàng)目貢獻(xiàn)代碼，而且是向這么優(yōu)秀的國產(chǎn)RTOS操作系統(tǒng)，還是很有成就感的~本篇文章記錄如何向RT-Thread或其他開源項(xiàng)目貢獻(xiàn)代碼，有不準(zhǔn)確的地方歡迎大家指正，希望大家支持國產(chǎn)RTOS的發(fā)展！

二、RT-Thread遵循的許可協(xié)議

RT-Thread的開源協(xié)議是進(jìn)行過調(diào)整的，在2018年RT-Thread官方公眾號(hào)發(fā)布的一篇文章[1]中，我們可以知道當(dāng)時(shí)是使用的GPLv2協(xié)議，

但是現(xiàn)在已經(jīng)是Apache-2.0協(xié)議了。

在貢獻(xiàn)代碼之前，我們有必要先來了解一下開源項(xiàng)目所遵循的協(xié)議，如果你提交成功，開源協(xié)議將會(huì)約束這些代碼被如何使用。從RT-Thread官方GitHub頁面，我們可以了解到RT-Thread所遵循的開源協(xié)議為：Apache-2.0 License，這個(gè)協(xié)議有以下特點(diǎn)：

• 永久權(quán)利
  一旦被授權(quán)，永久擁有。

• 全球范圍的權(quán)利
  在一個(gè)國家獲得授權(quán)，適用于所有國家。假如你在美國，許可是從印度授權(quán)的，也沒有問題。

• 授權(quán)免費(fèi)，且無版稅
  前期，后期均無任何費(fèi)用。

• 授權(quán)無排他性
  任何人都可以獲得授權(quán)

• 授權(quán)不可撤消
  一旦獲得授權(quán)，沒有任何人可以取消。比如，你基于該產(chǎn)品代碼開發(fā)了衍生產(chǎn)品，你不用擔(dān)心會(huì)在某一天被禁止使用該代碼。

有很多人認(rèn)為開源就是免費(fèi)，可以隨意的使用，其實(shí)這個(gè)觀點(diǎn)是錯(cuò)誤的。如果你有自己的開源項(xiàng)目，關(guān)于協(xié)議的選擇可以參考黃工大佬之前總結(jié)的[2]：程序猿如何選擇開源協(xié)議？

開源協(xié)議雖然不一定具備法律效力，但是當(dāng)涉及軟件版權(quán)糾紛時(shí)，開源協(xié)議也是非常重要的證據(jù)之一。

三、SmartFusion2 BSP簡介

這個(gè)BSP是移植 RT-Thread 操作系統(tǒng)到一款 FPGA 芯片——M2S010 ，該芯片屬于 Microsemi（現(xiàn)Microchip）SmartFusion2系列，是一款智能混合型FPGA，片上除了 FPGA Fabric 邏輯部分，還包括一個(gè) ARM? Cortex?-M3 內(nèi)核的 MCU，主頻最高 166MHz ，256KB eNVM，64KB eSRAM，集成GPIO、UART、I2C、SPI、CAN、USB等基本外設(shè)。

關(guān)于 Microsemi，第三大 FPGA 廠商，原 Actel 半導(dǎo)體，2010 年，Microsemi 收購 Actel，2018 年， Microchip 收購 Microsemi。

SmartFusion2 內(nèi)部框圖

移植了 RT-Thread 內(nèi)核，支持線程調(diào)度、線程間同步和通信等，已經(jīng)完成了PIN、Serial設(shè)備驅(qū)動(dòng)，F(xiàn)inSH組件默認(rèn)使用uart0設(shè)備。支持GPIO和UART外設(shè)，支持SCons構(gòu)建系統(tǒng)，可以輸入scons調(diào)用env工具中包含的arm-gcc編譯器構(gòu)建工程，支持以下scons命令：

• scons：使用arm-gcc編譯BSP

• scons -c：清除執(zhí)行 scons 時(shí)生成的臨時(shí)文件和目標(biāo)文件。

• scons --target=mdk4：重新生成Keil MDK4環(huán)境下的工程。

• scons --target=mdk5：重新生成Keil MDK5環(huán)境下的工程。

• scons --dist：打包BSP工程，包括RT-Thread源碼及BSP相關(guān)工程文件。

通過添加Kconfig文件，可以使用menuconfig來配置外設(shè)，用于生成rtconfig.h。

四、如何提交你的BSP包

0.準(zhǔn)備工作

進(jìn)行提交之前，需要做一些準(zhǔn)備工作：

• 一個(gè)GitHub賬號(hào)
• Git Windows客戶 端(git-scm.com/download/win)
• 一些基本Git命令的使用，如 git clone/add/commit/pull/push/checkout等。
• 了解所使用處理器的啟動(dòng)流程，熟悉基本外設(shè)的使用，如GPIO、UART等。

1.Fork并Clone到本地PC

登錄自己的GitHub賬號(hào)，F(xiàn)ork RT-Thread倉庫到個(gè)人倉庫，F(xiàn)ork的意思可以理解為復(fù)制一份。

將遠(yuǎn)程倉庫下載到本地：git clone https://github.com/username/rt-thread，這樣就會(huì)把遠(yuǎn)程代碼下載到本地。

2.創(chuàng)建分支

從 master 分支創(chuàng)建自己的開發(fā)分支，如whik_sf2，可以使用命令：git checkout -b whik_sf2

3.開發(fā)你的BSP包

這是整個(gè)開發(fā)過程中最重要，也是最耗時(shí)的一步，如果是ARM內(nèi)核，可以參考STM32的移植過程，如果是其他內(nèi)核，就需要多用一點(diǎn)時(shí)間了。

編碼風(fēng)格參考：https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md

一個(gè)最基本的BSP包，至少應(yīng)該包括以下部分：

• 內(nèi)核移植，支持線程調(diào)度、線程間同步和通信

• 支持GPIO/UART外設(shè)，PIN/Serial設(shè)備驅(qū)動(dòng)

• 支持SCons構(gòu)建系統(tǒng)，可以使用arm-gcc進(jìn)行編譯，支持生成MDK工程，支持dist打包，通過SConscript、SConstruct、rtconfig.py文件實(shí)現(xiàn)

• 支持menuconfig配置外設(shè)，用于生成rtconfig.h，通過Kconfig文件實(shí)現(xiàn)

• README文件用于指導(dǎo)開發(fā)者如何使用這個(gè)BSP包，可以參考其他BSP文件夾下的README文件

提交關(guān)于BSP的代碼，盡量確保代碼改動(dòng)僅限制于BSP中，而不影響到其他代碼，否則可能會(huì)被拒絕[3]。

4.提交到遠(yuǎn)程并發(fā)起PR

如果本地進(jìn)行測試沒問題，就可以同步到遠(yuǎn)程了，三部曲：git add/commit/push，更新到遠(yuǎn)程之后，就可以發(fā)起PR了，在 git 倉庫中選擇自己修改了的分支，點(diǎn)擊 create Pull Request 按鈕發(fā)起 pull request。

在正式發(fā)起 Pull Request 之前，需要根據(jù) Preview 里面默認(rèn)的描述信息即 checklist 仔細(xì)核對(duì)代碼，在沒問題的 checklist 對(duì)應(yīng)選項(xiàng)復(fù)選框填寫[x]確認(rèn)，注意[x]兩邊沒有空格。比如若代碼是成熟版本，請(qǐng)選擇成熟版本，且可以添加相應(yīng)的描述信息，checklist 核對(duì)完成才可發(fā)起 Pull Request。

第一次為 RT-Thread 貢獻(xiàn)代碼需要需要簽署 Contributor License Agreement。

請(qǐng)確認(rèn) CLA 顯示簽署成功及 CI 編譯通過，如下圖所示：

提交PR之后，就會(huì)獲得一個(gè)PR#號(hào)碼，在https://github.com/RT-Thread/rt-thread/pulls可以看到所有的PR請(qǐng)求，其中應(yīng)該會(huì)包含你的。如果是Open狀態(tài)，說明正在進(jìn)行代碼審查，還沒有合并到主分支。

5.代碼審查

一個(gè)完善的BSP，往往不是一次性就能提交成功的。提交PR后，要多看看反饋， 項(xiàng)目管理者會(huì)對(duì)提交的代碼進(jìn)行審查，如果有問題會(huì)在對(duì)應(yīng)的PR下面進(jìn)行評(píng)論，提出修改意見，就像下面這樣：

PR只需要提交一次，每次根據(jù)修改意見進(jìn)行修改之后，項(xiàng)目管理者會(huì)看到你的修改，并再次審查修改之后的代碼，一般需要2個(gè)或以上的項(xiàng)目管理者進(jìn)行審查，如果代碼沒有問題，就可以進(jìn)行以下步驟了。

6.添加到CI自動(dòng)化編譯

如果是提交的完整BSP，可以將BSP添加到CI編譯腳本，使用遠(yuǎn)程主機(jī)對(duì)BSP進(jìn)行編譯，和本地使用arm-gcc scons編譯是一樣的，如果本地編譯正常，這一步基本也會(huì)通過。

7.等待合并

如果CI編譯成功，而且審查通過，這個(gè)PR會(huì)依次被標(biāo)記為+1、+2，此時(shí)只需要耐心等待幾天，直到最終被合并到主分支上。

我提交的這個(gè)BSP過程可以參考：

https://github.com/RT-Thread/rt-thread/pull/3661

五、除了代碼還能向開源項(xiàng)目貢獻(xiàn)什么？

為開源項(xiàng)目做貢獻(xiàn)我們可以分為兩大類:代碼類貢獻(xiàn)和非代碼類貢獻(xiàn)。

代碼貢獻(xiàn)

• BUG修復(fù)

• 軟件包開發(fā)

• BSP提交

• 內(nèi)核開發(fā)

非代碼貢獻(xiàn)

• 撰寫和改進(jìn)文檔

• 通過實(shí)例來展示RT-Thread的使用

• 為RT-Thread撰寫教程，如學(xué)習(xí)筆記、常見問題等

• 官方社區(qū)發(fā)布自己的經(jīng)驗(yàn)文章，或積極回復(fù)帖子的問題

六、注意事項(xiàng)

• 不要使用非GitHub賬號(hào)提交

• 不要使用不同賬號(hào)提交Commit之后提交PR，會(huì)導(dǎo)致CLA簽署失敗

• 編程風(fēng)格遵守documentation 目錄下的 coding_style_cn.txt文件。

• 不接受5個(gè)以上的Commit

七、總結(jié)

向開源項(xiàng)目貢獻(xiàn)代碼，提交PR，可以通俗的理解，這里摘自知乎[4]網(wǎng)友的一段解釋：

我嘗試用類比的方法來解釋一下pull reqeust。想想我們中學(xué)考試，老師改卷的場景吧。你做的試卷就像倉庫，你的試卷肯定會(huì)有很多錯(cuò)誤，就相當(dāng)于程序里的bug。老師把你的試卷拿過來，相當(dāng)于先fork。在你的卷子上做一些修改批注，相當(dāng)于git commit。最后把改好的試卷給你，相當(dāng)于發(fā)pull request，你拿到試卷重新改正錯(cuò)誤，相當(dāng)于merge。

當(dāng)你想更正別人倉庫里的錯(cuò)誤時(shí)，要按照下面的流程進(jìn)行：

先 fork 別人的倉庫，相當(dāng)于拷貝一份別人的資料。因?yàn)椴荒鼙ＷC你的修改一定是正確的，對(duì)項(xiàng)目有利的，所以你不能直接在別人的倉庫里修改，而是要先fork到自己的git倉庫中。clone 到自己的本地分支，做一些 bug fix，然后發(fā)起 pull request給原倉庫，讓原倉庫的管理者看到你提交的修改。

原倉庫的管理者 review 這個(gè) bug，如果是正確的話，就會(huì) merge 到他自己的項(xiàng)目中。merge 的意思就是合并，將你修改的這部分代碼合并到原來的倉庫中添加代碼或者替換掉原來的代碼。至此，整個(gè) Pull Request 的過程就結(jié)束了。

參考資料

[1]. 如何開啟RT-Thread社區(qū)貢獻(xiàn)之路
https://mp.weixin.qq.com/s/JfVYB0yUcbyxa5EVWY4DKw

[2]. 五種開源協(xié)議(GPL,LGPL,BSD,MIT,Apache)

https://www.oschina.net/question/54100_9455

[3]. 在Github上為RT-Thread貢獻(xiàn)代碼，為自己的人生涂色
https://mp.weixin.qq.com/s/pPGunFzGcfz01pugNnWCiA

[4]. GitHub 的 Pull Request 是指什么意思？
https://www.zhihu.com/question/21682976