TOPPERSとFreeRTOSのAPIを比べてみる

# 目的

最近、電子工作向けのデバイスのソフトウェアには[FreeRTOS](https://www.freertos.org/index.html)が使われているのをよく目にするようになりました。
FreeRTOSのAPIとTOPPERSのAPIを並べて理解を深め、RTOSの利用の参考になれば良いかなと思い、この記事を書きました。
まだ、FreeRTOSは意識して使ったことがないので、[GR-ROSE](https://www.renesas.com/jp/ja/products/gadget-renesas/boards/gr-rose)や[Wio Terminal](https://wiki.seeedstudio.com/jp/Wio-Terminal-Getting-Started/)を利用して、TOPPERSで動かそうとした時に自分でも参考にしようと思ってます。

## FreeRTOS

Amazon Web Servicesがデバイス向けに提供しているRTOSが[FreeRTOS](https://aws.amazon.com/jp/freertos/)になります。
クラウドサービスを提供する企業がデバイス向けのRTOSを提供するのは、IoTシステムを構築するには、デバイス側のソフトウェアも重要でRTOSが有用なソフトウェアだからだと思います。

## μITRONとTOPPERS

RTOSは古くからあるソフトウェアで、日本ではμITRONが多く使われてきたようですが、TOPPERSもμITRONから発展したRTOSを提供しています。
μITRONはAPI仕様だけの規格なのですが、TOPPERSプロジェクトではOSSとしてAPIを実装したものを提供してきました。
IoT時代でも有用なソフトウェアだと思っています。

# それぞれのAPIリファレンス

FreeRTOSのAPIリファレンスは下記のサイトにあります。
https://www.freertos.org/Documentation/RTOS_book.html

TOPPERSのAPIリファレンスは下記のサイトにあります。
https://www.toppers.jp/documents.html

APIは思ったより量があるので、掻い摘んで書きたいと思います。

## 動作検証

現段階では、動作検証していません。APIの説明を見て対応付けしただけです。

動作検証に使えそうなデバイスとして、Wio Terminalを使おうと思っています。Wio Terminalには開発元から[FreeRTOS](https://github.com/Seeed-Studio/Seeed_Arduino_FreeRTOS)が提供されています。
また、[TOPPERS/ASP Arduino ライブラリ（TA2LIB）](https://github.com/exshonda/Arduino_TOPPERS_ASP)があります。

両方とも[Arduino IDE](https://www.arduino.cc/en/Main.Software)で使用できるので、APIの動作を同じ環境で試すことが出来ますので、これを使おうと思います。

注意として、TA2LIBのAPIは標準のTOPPERS/ASPのAPIに加えて、動的生成がサポートされています。
TOPPERS/ASPの動的生成機能拡張パッケージでは、オブジェクトの生成とIDの採番を行う```acre_xxx```というAPIがありますが、これとは違い、TA2LIBではあらかじめ定義されたIDでオブジェクトを生成する```cre_xxx```というAPIを使います。

下記のAPI比較はTA2LIBのAPIを使用しています。

また、FreeRTOSが載ったGR-ROSEというボードあり、日本語でFreeRTOSの[使い方](https://www.renesas.com/jp/ja/products/gadget-renesas/reference/gr-rose/rtos-overview)が載っているので、こちらも参考にしました。

# タスクとスケジューラ―

## タスクの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xTaskCreate|cre_tsk stk=NULL|
|xTaskCreateStatic|cre_tsk stk=Memory|
|vTaskDelete|del_tsk|

## タスク制御

|FreeRTOS|TOPPERS|
|---|---|
|vTaskDelay|dly_tsk|
|vTaskDelayUntil|-|
|uxTaskPriorityGet|get_pri|
|vTaskPrioritySet|chg_pri|
|vTaskSuspend|sus_tsk|
|vTaskResume|rsm_tsk|
|xTaskResumeFromISR|-|
|xTaskAbortDelay|rel_wai|

# キュー

## キューの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xQueueCreate|cre_dtq pk_cdtq->dtqmb=NULL|
|xQueueCreateStatic|cre_dtq pk_cdtq->dtqmb=Memory|
|vQueueDelete|del_dtq|

## キューの操作

|FreeRTOS|TOPPERS|
|---|---|
|xQueueSend|snd_dtq/psnd_dtq/tsnd_dtq|
|xQueueSendToBack|snd_dtq/psnd_dtq/tsnd_dtq|
|xQueueSendToFront|-|
|xQueueSendFromISR|ifsnd_dtq|
|xQueueSendToBackFromISR|ifsnd_dtq|
|xQueueSendToFrontFromISR|-|
|xQueueReceive|rcv_dtq/prcv_dtq/trcv_dtq|
|xQueueReceiveFromISR|-|
|uxQueueMessagesWaiting|ref_dtq|
|uxQueueMessagesWaitingFromISR|-|
|uxQueueSpacesAvailable|-|
|xQueueReset|ini_dtq|
|xQueueOverwrite|fsnd_dtq|
|xQueueOverwriteFromISR|ifsnd_dtq|
|xQueuePeek|-|
|xQueuePeekFromISR|-|
|vQueueAddToRegistry|-|
|vQueueUnregisterQueue|-|
|pcQueueGetName|-|
|xQueueIsQueueFullFromISR|-|
|xQueueIsQueueEmptyFromISR|-|

# キューセット

TOPPERSには見当たりませんでした。

|FreeRTOS|TOPPERS|
|---|---|
|xQueueCreateSet|-|
|xQueueAddToSet|-|
|xQueueRemoveFromSet|-|
|xQueueSelectFromSet|-|
|xQueueSelectFromSetFromISR|-|

# セマフォ

FreeRTOSではセマフォとミューテックスは同じハンドラで操作しますが、TOPPERSでは分かれているのでミューテックスは別の章にしました。
また、FreeRTOSではBinary版とCounting版がありますが、詳しい違いはわかってません。

## セマフォの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xSemaphoreCreateBinary|-|
|xSemaphoreCreateBinaryStatic|-|
|xSemaphoreCreateCounting|cre_sem|
|xSemaphoreCreateCountingStatic|cre_sem|
|vSemaphoreDelete|del_sem|

## セマフォの操作

|FreeRTOS|TOPPERS|
|---|---|
|xSemaphoreGetMutexHolder|ref_sem|
|uxSemaphoreGetCount|ref_sem|
|xSemaphoreTake|wai_sem/pwai_sem/twai_sem|
|xSemaphoreTakeFromISR|-|
|xSemaphoreTakeRecursive|-|
|xSemaphoreGive|sig_sem|
|xSemaphoreGiveFromISR|isig_sem|
|xSemaphoreGiveRecursive|-|

# ミューテックス

ミューテックスはTA2LIBにはないが、TOPPERS/ASPの拡張パッケージにあるので表は埋めておきます。
FreeRTOSでは無印Mutex版とRecursiveMutex版がありますが、詳しい違いはわかってません。

## ミューテックスの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xSemaphoreCreateMutex|cre_mtx|
|xSemaphoreCreateMutexStatic|cre_mtx|
|xSemaphoreCreateRecursiveMutex|-|
|xSemaphoreCreateRecursiveMutexStatic|-|
|vSemaphoreDelete|del_mtx|

## ミューテックスの操作

|FreeRTOS|TOPPERS|
|---|---|
|uxSemaphoreGetCount|-|
|xSemaphoreGetMutexHolder|ref_mtx|
|xSemaphoreGive|unl_mtx|
|xSemaphoreGiveFromISR|-|
|xSemaphoreGiveRecursive|-|
|xSemaphoreTake|loc_mtx/ploc_mtx/tloc_mtx|
|xSemaphoreTakeFromISR|-|
|xSemaphoreTakeRecursive|-|

# イベントグループ

TOPPERSではイベントフラグに相当すると思われます。

## イベントグループの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xEventGroupCreate|cre_flg|
|xEventGroupCreateStatic|cre_flg|
|vEventGroupDelete|del_flg|

## イベントグループの操作

|FreeRTOS|TOPPERS|
|---|---|
|xEventGroupWaitBits|wai_flg/pwai_flg/twai_flg|
|xEventGroupSetBits|set_flg|
|xEventGroupSetBitsFromISR|iset_flg|
|xEventGroupClearBits|clr_flg|
|xEventGroupClearBitsFromISR|-|
|xEventGroupGetBits|ref_flg|
|xEventGroupGetBitsFromISR|-|
|xEventGroupSync|-|

# ストリームバッファ

ストリームバッファはTA2LIBにも他のTOPPERSカーネルにも見当たりませんでした。
FreeRTOSでは注意書きがあり、他のタスク間通信オブジェクトと違い、１対１の送信を前提とした機能のようです。
特定の割り込みルーチンから特定のタスクへの送信や、ある特定のタスクから別の特定のタスクへの送信のみに利用できるようです。

## ストリームバッファの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xStreamBufferCreate|-|
|xStreamBufferCreateStatic|-|
|vStreamBufferDelete|-|

## ストリームバッファの操作

|FreeRTOS|TOPPERS|
|---|---|
|xStreamBufferReceive|-|
|xStreamBufferReceiveFromISR|-|
|xStreamBufferReset|-|
|xStreamBufferSend|-|
|xStreamBufferSendFromISR|-|
|xStreamBufferSetTriggerLevel|-|
|xStreamBufferSpacesAvailable|-|
|xStreamBufferBytesAvailable|-|
|xStreamBufferIsEmpty|-|
|xStreamBufferIsFull|-|

# メッセージバッファ

メッセージバッファはTA2LIBにはないが、TOPPERS/ASPの拡張パッケージにあるので表は埋めておきます。

## メッセージバッファの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xMessageBufferCreate|cre_mbf|
|xMessageBufferCreateStatic|cre_mbf|
|vMessageBufferDelete|del_mbf|

## メッセージバッファの操作

|FreeRTOS|TOPPERS|
|---|---|
|xMessageBufferSend|snd_mbf/psnd_mbf/tsnd_mbf|
|xMessageBufferSendFromISR|-|
|xMessageBufferReceive|rcv_mbf/prcv_mbf/trcv_mbf|
|xMessageBufferReceiveFromISR|-|
|xMessageBufferReset|ini_mbf|
|xMessageBufferSpacesAvailable|ref_mbf|
|xMessageBufferIsEmpty|ref_mbf|
|xMessageBufferIsFull|ref_mbf|

# ソフトウェアタイマー

FreeRTOSのソフトウェアタイマーは、TOPPERSの周期ハンドラとアラームハンドラに相当しそうです。
FreeRTOSのソフトウェアタイマー構築時に、`uxAutoReload=pdTRUE`としたものが周期ハンドラで、`uxAutoReload=pdFALSE`としたものがアラームハンドラと同等の機能になります。

FreeRTOSではソフトウェアタイマー用のタスクからハンドラーが呼ばれるようですが、TOPPERSでは非タスクコンテキストでハンドラーが呼ばれます。

## ソフトウェアタイマーの生成と破棄

|FreeRTOS|TOPPERS|
|---|---|
|xTimerCreate|cre_cyc/cre_alm|
|xTimerCreateStatic|cre_cyc/cre_alm|
|xTimerDelete|-|

## ソフトウェアタイマーの操作

|FreeRTOS|TOPPERS|
|---|---|
|xTimerIsTimerActive|ref_cyc/ref_alm|
|xTimerStart|sta_cyc/sta_alm|
|xTimerStartFromISR|-/ista_alm|
|xTimerStop|stp_cyc/stp_alm|
|xTimerStopFromISR|-/istp_alm|
|xTimerChangePeriod|(cre_cyc)/(cre_alm)|
|xTimerChangePeriodFromISR|-|
|xTimerReset|-/-|
|xTimerResetFromISR|-/-|
|pvTimerGetTimerID|-/-|
|vTimerSetTimerID|-/-|
|xTimerGetTimerDaemonTaskHandle|-/-|
|xTimerPendFunctionCall|-/-|
|xTimerPendFunctionCallFromISR|-/-|
|pcTimerGetName|-/-|
|xTimerGetPeriod|-/-|
|xTimerGetExpiryTime|ref_cyc/ref_alm|

# まとめ

FreeRTOSの基本のAPIについて、TOPPERSでもおおむね提供されていた。FreeRTOSでは割り込みルーチンから呼べるAPIが多いようだった。
今後、動作検証も行いこの記事を更新し、もう少し詳しくし書いていこうと思います。