LoginSignup
1

More than 1 year has passed since last update.

posted at

updated at

Organization

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

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

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

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

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

仕様書のある場所

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

toppers-top.png

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

toppers-doc.png

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

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

PDFとhtmlの2つ?

ここも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文字 の形ということがわかります。3文字略語にするとわかりにくいから、4文字にしよう!ということは無いということですね。

ただし、続きに

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

とあります。
つまり、4文字_3文字 とか、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」をつけてみましょう。


  1. 私は、can_wup()のcanがcanselとは思わなかった :sweat_smile:  

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
1