TOPPERSのAPIの意味わかりますか？-統合仕様書を読んでみよう-

こんにちは、TOPPERSの初心者向け記事担当です。

TOPPERSにはさまざまなAPIがありますが、みなさんはAPIの名前からその意味が読み取れるでしょうか。
`slp_tsk()` は `sleep task` 、 `act_tsk()` は `activate task` あたりはわかると思うのですが、 `rot_rdq()` とか、 `rel_wai()` 、 `ras_ter()` あたりはどうでしょう？ [^fn1]
先日とある人（初心者ではない）と話していて、わかりづらいよねーということになったので、こちらで紹介しようと思います。

# すべて統合仕様書に載っている

TOPPERS カーネルの開発者、高田先生曰く、「用語の定義から全て統合仕様書に載っている」とのこと。
統合仕様書については、 TOPPERS Advent Calendar 13日目の「統合仕様書リッチテキスト化への道のり的なお話」に書かれると思うので、そちらを楽しみに待ちましょう。

## 仕様書のある場所

13日の記事が公開されたら、改めて書き直したいと思いますが、統合仕様書のPDFは[TOPPERSのサイト]( https://www.toppers.jp/index.html )にあります。
ダウンロードやドキュメントは（左側のツリーメニューよりも、上のメニューの方を使っている人が多いみたいです。（半径３メートル範囲の調査））
というわけでh、以下の図の丸をつけたDocumentをクリックしてみましょう。

![toppers-top.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/61488/40199da2-ec0d-18ed-b177-eb88f61a51f6.png)


こんな感じで「統合仕様書」のページが表示されます。
一番上に最新がくるようになっています。


![toppers-doc.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/61488/31790232-edc1-64a7-790b-4dd9c367db05.png)

ちなみに、EV3RTの1.0以降はTOPPERS第3世代カーネル（ITRON系）統合仕様書、β7-xなど、それ以前のものは、もう少し下の方にあるTOPPERS新世代カーネル統合仕様書が対応しています。

本記事では、**TOPPERS第3世代カーネル（ITRON系）統合仕様書** の方を元に解説します。
（とはいえ、第３世代の名の通り、こちらはTOPPERS新世代カーネルがバージョンアップされたものです。資料の基本的な作りは同じなので、EV3RTのベータ版や(ASP3ではなくて)ASPを使っている人は、「TOPPERS新世代カーネル統合仕様書」の該当箇所に読み替えてください。）

## PDFとhtmlの２つ？
ここも13日の記事で説明があると思うので本稿では省略しますが、上記で紹介したPDFの他に、htmlとして出力してGitHubで公開されているものがあります。

html化したものはhttps://github.com/mitsut/toppers_kernel_spec にあります。

PDFの最新版はつい先月公開されたばかりなので、そのうちhtmlの方も更新されると思います。

本稿は説明の都合上、リンクを貼れる方が便利なので、一つ前のRelease 3.4.1ですが、 https://mitsut.github.io/toppers_kernel_spec/tgki_spec-341.html を使います。
（差分が気になる人は、[Release 3.4.2]( https://www.toppers.jp/docs/tech/tgki_spec-342.pdf ) の　`A.5 Release 3.4.1とRelease 3.4.2の差分` を参照してください）

## 

前置きが長くなってしまいましたが、ようやく本題に入ります。
仕様書の読み方については、高田先生が[ソフトウェアプラットフォームとRTOSの基礎 Part3（2020年度ETロボコン向けTOPPERS活用セミナー)]( https://youtu.be/hTCkByrYjv8 )の中で説明しているので、そちらを見るのが良いでしょう。
名前づけルールは、[2.13 TOPPERSネーミングコンベンション](https://mitsut.github.io/toppers_kernel_spec/tgki_spec-341.html#_2_13_toppers%E3%83%8D%E3%83%BC%E3%83%9F%E3%83%B3%E3%82%B0%E3%82%B3%E3%83%B3%E3%83%99%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%B3)にあります。

これを読み進めていくと、 [2.13.3 関数名](https://mitsut.github.io/toppers_kernel_spec/tgki_spec-341.html#_2_13_3_%E9%96%A2%E6%95%B0%E5%90%8D) があります。

> 2.13.3 関数名
関数の名称は，英小文字，数字，"_"で構成する．
関数の種類毎に，次のネーミングコンベンションを定める．
> 
> (A) サービスコール
> 
> サービスコールは，xxx_yyyまたはwww_xxx_yyyの名称とする．ここで，xxxは操作の方法，yyyは操作の対象を表す

念のため補足しておくと、xとかyは英小文字または数字1文字を表しています。
ここから、API名は、`3文字_３文字` の形ということがわかります。3文字略語にするとわかりにくいから、4文字にしよう！ということは無いということですね。

ただし、続きに
> xxx_yyyまたはwww_xxx_yyyから派生したサービスコールは，それぞれzxxx_yyyまたはwww_zxxx_yyyの名称とする．ここでzは，派生したことを表す文字である．派生したことを表す文字を2つ付加する場合には，zzxxx_yyyまたはwww_zzxxx_yyyの名称となる．

とあります。
つまり、`4文字_３文字` とか、`5文字_3文字` になる場合もあるけど、これは、 `xxx_yyy`の派生形ということがわかります。
わかりやすい例でいうと、

```
slp_tsk　起床待ち
tslp_tsk　起床待ち（タイムアウト付き)
```
という感じです。

もう少し読んでいくと、以下の文章が出てきます。

> 【補足説明】
> サービスコールの名称を構成する省略名（xxx，yyy，z）の元になった英語については，「5.10 省略名の元になった英語」の節を参照すること．

ということから、xxxとかyyyとかzについては [5.10 省略名の元になった英語]( https://mitsut.github.io/toppers_kernel_spec/tgki_spec-341.html#_5_10_%E7%9C%81%E7%95%A5%E5%90%8D%E3%81%AE%E5%85%83%E3%81%AB%E3%81%AA%E3%81%A3%E3%81%9F%E8%8B%B1%E8%AA%9E ) に書いてあることがわかります。

冒頭で紹介したrot_rdq() とか、 rel_wai() 、 ras_ter() の正解は、この一覧を参照すると、

| xxx | 元になった英語 |
|:-:|:-:|
| rot | rotate |
| rel | release |
| ras | raise |

| yyy | 元になった英語 |
|:-:|:-:|
| rdq | ready queue |
| wai | wait |
| ter | termination |

rot_rdq() は、rotate ready queue、rel_wai()はrelease wait、 ras_ter()はraise termination ということがわかりました。
ぜひ、みなさんが使っているAPIの名前についても調べてみてください。思っていたとおりの結果になったでしょうか？

先ほど挙げた例の`tslp_tsk`の「t」は何？についても、もうわかりますね。
これについては、[5.10.3 サービスコールの名称の中のzの元になった英語](https://mitsut.github.io/toppers_kernel_spec/tgki_spec-341.html#_5_10_3_%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%AB%E3%81%AE%E5%90%8D%E7%A7%B0%E3%81%AE%E4%B8%AD%E3%81%AEz%E3%81%AE%E5%85%83%E3%81%AB%E3%81%AA%E3%81%A3%E3%81%9F%E8%8B%B1%E8%AA%9E)にあります。

| z | 元になった英語 |
|:-:|:-:|
| t | timeout |


もし、ここで、 `サービスコールは，xxx_yyyまたはwww_xxx_yyyの名称とする`の`www`は何？と思った人がいたら、 `2.13 TOPPERSネーミングコンベンション` をもう一度読み直してくださいね。

さらに、`rot_rdq() は、rotate ready queue`はわかったけど,`ready queue`って何？仕様書に書いてないよ？って思った人は、「レディキュー RTOS」などでググってみてください。（RTOSををつけると、無関係の結果が減ります。TOPPERSやITRON関連の場合、カタカナ表記でググる方が検索にかかりやすいように思います。）
この統合仕様書では、TOPPERSやμITRONで定義した用語の説明を書いています。
もし、記載がなくてわからないことがあれば、ググってみることをおすすめします。


# まとめ
TOPPERSには統合仕様書ってものがあって、TOPPERSに関することは何でも書いてあります。

載っていなくて、わからないことがあれば一般用語の可能性がきわめて高いので、ググってください。
ググるって無関係な結果が多過ぎて困ったら、検索キーワードに「RTOS」をつけてみましょう。


[^fn1]: 私は、can_wup()のcanがcanselとは思わなかった :sweat_smile: