こんにちは、TOPPERSの初心者向け記事担当です。
TOPPERSにはさまざまなAPIがありますが、みなさんはAPIの名前からその意味が読み取れるでしょうか。
slp_tsk() は sleep task 、 act_tsk() は activate task あたりはわかると思うのですが、 rot_rdq() とか、 rel_wai() 、 ras_ter() あたりはどうでしょう？ 1
先日とある人（初心者ではない）と話していて、わかりづらいよねーということになったので、こちらで紹介しようと思います。
すべて統合仕様書に載っている
TOPPERS カーネルの開発者、高田先生曰く、「用語の定義から全て統合仕様書に載っている」とのこと。
統合仕様書については、 TOPPERS Advent Calendar 13日目の「統合仕様書リッチテキスト化への道のり的なお話」に書かれると思うので、そちらを楽しみに待ちましょう。
仕様書のある場所
13日の記事が公開されたら、改めて書き直したいと思いますが、統合仕様書のPDFはTOPPERSのサイトにあります。
ダウンロードやドキュメントは（左側のツリーメニューよりも、上のメニューの方を使っている人が多いみたいです。（半径３メートル範囲の調査））
というわけでh、以下の図の丸をつけたDocumentをクリックしてみましょう。
こんな感じで「統合仕様書」のページが表示されます。
一番上に最新がくるようになっています。
ちなみに、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 の A.5 Release 3.4.1とRelease 3.4.2の差分 を参照してください）
前置きが長くなってしまいましたが、ようやく本題に入ります。
仕様書の読み方については、高田先生がソフトウェアプラットフォームとRTOSの基礎 Part3（2020年度ETロボコン向けTOPPERS活用セミナー)の中で説明しているので、そちらを見るのが良いでしょう。
名前づけルールは、2.13 TOPPERSネーミングコンベンションにあります。
これを読み進めていくと、 2.13.3 関数名 があります。
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 省略名の元になった英語 に書いてあることがわかります。
冒頭で紹介した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の元になった英語にあります。
| 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」をつけてみましょう。
-
私は、can_wup()のcanがcanselとは思わなかった
↩