SOLID for Raspberry Pi 4 (連載21)

前回書いたプログラムや内容について、有識者の方に読んでいただき、フィードバックを頂きました。

今回はその内容について記載します。

前回、SPI転送完了割り込みの優先度について、とりあえず 10 固定にしました。

今回は、SOLID-OSのSOLID_INTC_GetPriorityLevel()関数を使って、システムで許されている最大値を取得し、その付近の値を優先度として設定してみます。

SOLID_INTC_GetPriorityLevel()関数は、solidクレートの中で、C言語の関数をコールするためのWrapperが定義されています。。

https://github.com/KyotoMicrocomputer/solid-rapi4-examples/blob/main/common/solid/src/abi.rs

solidクレートの中の、abiの中にあるので、

solid::abi::SOLID_INTC_GetPriorityLevel()

で使用できます。

さらに、C言語なので戻り値がc_int型です。

i32型に変換するため、
.into()
を付けます。

すると、今度は unsafeだよ！と怒られました。

という事で、unsafe{ }で囲んだところ、エラーがなくなりました。

let spi_handler_option = interrupt::HandlerOptions::new(interrupt::Number(150), unsafe{solid::abi::SOLID_INTC_GetPriorityLevel().into()});

このコードを実行してみます。

max_priorityには何が入っているでしょうか。

16ですね。
– 2 として、優先順位14あたりがいいかもしれません。

let max_priority: i32 = unsafe{solid::abi::SOLID_INTC_GetPriorityLevel().into()};
let spi_handler_option = interrupt::HandlerOptions::new(interrupt::Number(150),  max_priority - 2);

前回、
「singleton::pin_singleton, thread::CpuCxについては、今回は「おまじない」という事でご容赦ください。。。」
でごまかしたご容赦頂いた部分ですが、フィードバック頂きました。

ものすごく簡単にイメージだけで言うと、
・pin_singleton!
プログラムを実行中に1回だけ走らせるという事ができ（シングルトン）、かつ、割り込み構造体等ずっと同じメモリに留め置く（ピン）型のみ受け付けるマクロ。ハードウェアの初期設定時に使うと便利。

・CpuCx<'a>
SOLID_CPU_CONTEXTのラッパー。

以下、下手に自分の言葉で書こうとせず、フィードバック頂いた内容をそのまま引用することにします。

[solid::singleton::pin_singleton!]
指定した式でグローバル変数を初期化し、変数への参照を Pin<&'static mut _> (pinned reference) として返すマクロです。プログラムを実行中に1回だけこれができ、2回目以降は Err(_) を返します。

 

ポイントを挙げると以下の通りです。
• グローバル変数を定義する
• 変数を実行時に初期化して、'static mutable 参照を返す
• 2回目以降は失敗する
• 単なる参照 (unpinned reference) ではなくpinned referenceを返す

solid::interrupt::Handler と solid::timer::Timer を静的割当てする実装アプローチを取る場合に、コードを簡潔にすることが目的です。実行時に初期化するので、ローカル変数をハンドラ関数 (クロージャ―) にmoveすることも可能です (rust-blinky-pac-ap804の例)。
動作イメージとしては以下のようになります (シングルスレッド、非リエントラント仮定)。

// let foo = pin_singleton!(: Handler<_> = Handler::new(HandlerFn));
   let foo = unsafe {
      static mut VAR: Handler;
      static mut INIT: bool;
      if !INIT {
         INIT = true;
         VAR = Handler::new(HandlerFn);
         Ok(Pin::static_mut(&mut VAR))
      } else {
         Err(todo!())
      }
   };

solid::interrupt::Handler に含まれる SOLID_INTC_HANDLER 構造体は、SOLID_INTC_Register 関数のAPI規約上、割込みハンドラが登録されている間はずっと同じメモリ番地に存在し続けなければなりません (i.e., Safe Rustからこれを違反できてはいけません)。
この制約を型で表現するのが、 Pin<&'static mut Handler> のようなpinned referenceです。solid::timer::Timer も同様で、これらの型のメソッドはpinned referencesのみを受け付けます。

Pinned referencesを作るには次の方法があります。
1. 最も簡単な方法は Box::pin で値をヒープに移して Pin<Box> スマートポインタを得ることです (rust-blinky-pac-csの古い例)。
2. あるいは Box::new から Box::leak して得られる &'static mut _ を Pin::static_mut に渡せば、 Pin<&'static mut _> が得られます (rust-blinky-pac-ap804の古い例)。
3. どちらの方法も動的メモリ割当てのオーバヘッドが掛かります。静的メモリ割当てすることは可能ですが、やや冗長なボイラープレートコードが必要になります (rust-server-gothamの古い例)。変数の動的な初期化が必要な場合、さらに冗長になります。
4. Pin::new_unchecked はpinned referenceの性質をプログラマが自らの責任で保証しなければならないため、unsafeコードからしか呼び出せません。
このマクロでは3つ目の方法を簡潔なコードで実現できるようにしています。

[solid::thread::CpuCx<'a>]
これは SOLID_CPU_CONTEXT のラッパーです。現時点では何もラッパーとしての付加機能はありませんが、ラッパーを介して渡すことにより追加の余地を残しています。
割込み発生時点のCPUレジスタの値を取得するのに使用できます (rust-server-gothamの例)。