[BUG] RL78 CCRLにてxEventGroupBitsFromISRが動作しない

Describe the bug

RL78にてxEventGroupBitsFromISR APIが正常に動作しない。
具体的にはportYIELD_FROM_ISR()が正常動作しないようだ。
正しい手順は「BRK実行→スタック退避→コンテキストスイッチ→スタックロード」ですが、実装ミスによりコンテキストスイッチだけやっているようです。従って元に戻れず動けない。

FreeRTOS-Kernel/portable/Renesas/RL78G2x/portmacro.h

Line 106 in ab7af2e

#define portYIELD_FROM_ISR( xHigherPriorityTaskWoken ) if( xHigherPriorityTaskWoken ) vTaskSwitchContext()

■誤り（現時点の記述）
#define portYIELD_FROM_ISR( xHigherPriorityTaskWoken ) if( xHigherPriorityTaskWoken ) vTaskSwitchContext()

■対策（修正）
RX600v2 の実装に合わせ、以下に変更することで直る。

#define portYIELD_FROM_ISR( x ) if( x != pdFALSE ) portYIELD()

[ShunichiroNakamura]

• 現時点の記述はAssembly ISR wrapperの実装を前提としたものであり、誤りという訳ではない。
  • Assembly ISR wrapperの詳細は、FreeRTOS.org: FreeRTOS for the Renesas RL78 MCU Using the IAR compilerを参照。
• 一方で、下記の理由により、Renesas製のツールやソフトウェアにとってAssembly ISR wrapperは少々都合が悪い。
  • 割り込み関連の汎用的な仕組みをRenesasが予め用意することが少々難しい。
    • Assembly ISR wrapperは割り込みハンドラごとに個別に作成する必要があるため、Assembly ISR wrapperの実装はユーザアプリケーションに依存してしまうため。
    • 汎用的な仕組み（Assembly ISR wrapper関数実行時に割り込みハンドラ関数を引数として渡すことで、割り込みハンドラごとにAssembly ISR wrapperを作成しなくて済む）を実装しようと思えば可能だが、port層にその機構を追加実装する必要がある。
  • ドライバソフトをAssembly ISR wrapper向けに改造することがサポート観点で少々難しい。
    • ユーザの省力化を目的として、RenesasはFreeRTOSとRenesas製ドライバソフトを簡単に組み合わせるためのツールを提供している。
    • しかし、このドライバソフトは基本的にBaremetal環境向けに設計されており、また、ドライバソフトには割り込みハンドラがすでに実装されているため、ドライバソフトをAssembly ISR wrapper向けに改造することでRenesasサポート対象外になってしまう。
• 本家リポジトリのメンテナーと協議した結果、Assembly ISR wrapper実装の要／不要をオプション化し、ユーザ（Renesas含む）都合に合わせて選択できる仕組みを導入する方針で決定した。
  • [BUG] xEventGroupBitsFromISR API doesn't work correctly for RL78 MCU(same as No.740 Issue) FreeRTOS/FreeRTOS-Kernel#1102

[ShunichiroNakamura]

• 上記方針にて本家リポジトリに PR & マージ完了
  • [Fixed the Issue] Fixed the Issue#1102 of RL78 of the Context switch … FreeRTOS/FreeRTOS-Kernel#1157
  • V11.2.0にて反映⇒https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/0adc196d4bd52a2d91102b525b0aafc1e14a2386/portable/GCC/RL78/portmacro.h#L112
• Renesas GitHubリポジトリに上記変更が反映されるまでこのIssueをOpenにしておく

[ShunichiroNakamura]

Conclusion

English follows Japanese.

Japanese

ISR wrapperとは

ISR wrapper (assembly file wrapper)とは、割り込みハンドラ（ISR）に対する入口処理と出口処理を実装するためのWrapper処理です。RL78向けFreeRTOSを使用するユーザーは、portYIELD_FROM_ISR()を実行する（コンテキストスイッチを実行する可能性がある）各割り込みハンドラに対してISR wrapperを実装する必要があります。具体的には、ユーザーは割り込みベクタにISR wrapperを登録（.VECTOR疑似命令を使用）し、入口処理はコンテキスト退避を、出口処理はコンテキスト復帰を実装します。
なお、RX, RA向けのFreeRTOSはISR wrapperを実装する必要がありません。これは、MCUアーキテクチャ仕様に差異があるため、portYIELD_FROM_ISR()の実装ポリシーもまたRL78向けFreeRTOSとRX, RA向けFreeRTOS間で異なるからです。

解決方法

使用するカーネルのバージョンに応じて以下の対応を実施してください。
また、ルネサスの提供サンプル(APN)を利用する場合は、後述するconfigREQUIRE_ASM_ISR_WRAPPERを0に設定してください。

V11.2.0以降

configREQUIRE_ASM_ISR_WRAPPERを設定してください。
configREQUIRE_ASM_ISR_WRAPPERは、ユーザーがISR wrapperを実装するかしないかを選択するConfigurationです。

設定値 (*1)	説明	長所	短所
0	ISR wrapperを実装しない (*2)	ISR wrapperを実装する手間が省ける (*3)	portYIELD_FROM_ISR()を割り込みハンドラの最後尾で実行しなければいけない (*4) メモリ消費量が増える (*5)
1	ISR wrapperを実装する	処理時間やメモリ消費量が効率的である	ユーザー自らがISR wrapperを実装する必要がある

• *1: デフォルト値は1です。
• *2: カーネルのportでISR wrapperの代替処理を実装済みですので、ユーザーはISR wrapperを実装する必要がありません。具体的には、ISR wrapperの入口処理や出口処理の代わりに、portYIELD_FROM_ISR()実行時にタスクスイッチ用の割り込みハンドラ（ソフトウェア割り込みのハンドラ）を呼び出すことで、コンテキスト退避／復帰を実行します。これは、RX, RA向けのFreeRTOSと同じ実装ポリシーです。
• *3: 例えば、外部から入手したドライバソフトウェアが割り込みハンドラを#pragma interruptでベクタ登録している場合、ISR wrapperを実装しない仕組みを利用することで、ユーザーはそのドライバソフトウェアのコード変更なしにportYIELD_FROM_ISR()を使用できます。
• *4: portYIELD_FROM_ISR()実行時にコンテキスト復帰が実行されるので、portYIELD_FROM_ISR()を実行した時点で即座にタスクに遷移します。したがって、仮に割り込みハンドラの処理の途中でportYIELD_FROM_ISR()を実行すると、後続の割り込み処理が中断します。
• *5: 割り込み発生時にコンテキストをスタックに退避する処理（コンパイラがこの処理をコード生成する）に加えて、portYIELD_FROM_ISR()実行時に再度コンテキスト退避が実行されます。そのため、portYIELD_FROM_ISR()を使用する割り込みハンドラにつき、その割り込み発生時のコンテキスト退避に消費されるメモリサイズが増分します。

V11.1.0以前

このバージョンでは、configREQUIRE_ASM_ISR_WRAPPER == 1 設定時と同じ動作をします。つまり、portYIELD_FROM_ISR()を実行する割り込みハンドラがある場合、ユーザーはそのハンドラに対するISR wrapperを実装する必要があります。
このバージョンでconfigREQUIRE_ASM_ISR_WRAPPERを利用できるように、ソースコードを以下のように変更してください。

変更対象のソースファイル

• ./portable/Renesas/RL78/portmacro.h
• ./portable/Renesas/RL78G2x78/portmacro.h

変更前

#define portYIELD_FROM_ISR( xHigherPriorityTaskWoken ) if( xHigherPriorityTaskWoken ) vTaskSwitchContext()

変更後

#ifndef configREQUIRE_ASM_ISR_WRAPPER
    #define configREQUIRE_ASM_ISR_WRAPPER    1
#endif
#if( configREQUIRE_ASM_ISR_WRAPPER == 1 )
    /* You must implement an assembly ISR wrapper (see the below for details) if you need an ISR to cause a context switch.
     * https://www.freertos.org/Documentation/02-Kernel/03-Supported-devices/04-Demos/Renesas/RTOS_RL78_IAR_Demos#writing-interrupt-service-routines */
    #define portYIELD_FROM_ISR( xHigherPriorityTaskWoken )    do { if( xHigherPriorityTaskWoken != pdFALSE ) vTaskSwitchContext(); } while( 0 )
#else
    /* You must not implement an assembly ISR wrapper even if you need an ISR to cause a context switch.
     * The portYIELD, which is similar to role of an assembly ISR wrapper, runs only when a context switch is required. */
    #define portYIELD_FROM_ISR( xHigherPriorityTaskWoken )    do { if( xHigherPriorityTaskWoken != pdFALSE ) portYIELD(); } while( 0 )
#endif

English

What is an ISR wrapper?

An ISR wrapper (assembly file wrapper) is a wrapper routine that implements the entry and exit processing for an interrupt handler (ISR). When using FreeRTOS for RL78, users must implement an ISR wrapper for each interrupt handler that calls portYIELD_FROM_ISR() (which may trigger a context switch). Specifically, the user registers the ISR wrapper in the interrupt vector table using the .VECTOR directive, and implemtents context saving in the entry processing and context restoring in the exit processing.
Note that ISR wrappers are not required for FreeRTOS for RX and RA. This is because the MCU architectures differ, and consequently, the implementation policies for portYIELD_FROM_ISR() also differ between FreeRTOS for RL78 and FreeRTOS for RX/RA.

Solution

Please take the following actions depending on the version of the kernel you are using.
In addition, when using Renesas-provided sample applications (APNs), set configREQUIRE_ASM_ISR_WRAPPER, which is described later, to 0.

For version 11.2.0 or later

Please configure configREQUIRE_ASM_ISR_WRAPPER.
This configuration determines whether the user is required to implement an ISR wrapper.

Setting value (*1)	Description	Advantages	Disadvantages
0	Not implementing an ISR wrapper (*2)	Eliminates the need for the user to implement an ISR wrapper (*3)	portYIELD_FROM_ISR() must be called at the end of the interrupt handler (*4) Memory usage increases (*5)
1	Implementing an ISR wrapper	More efficient in terms of execution time and memory usage	The user must implement the ISR wrapper themselves

• *1: The default value is 1.
• *2: Since an alternative mechanism for ISR wrappers has already been implemented in the kernel port, users do not need to implement ISR wrappers. Specifically, instead of performing the entry and exit processing in an ISR wrapper, context saving and restoring are executed by invoking the task‑switch interrupt handler (software interrupt handler) when portYIELD_FROM_ISR() is called. This implementation policy is the same as that used for FreeRTOS for RX and RA.
• *3: For example, if a driver software obtained from an external source registers interrupt handlers in the interrupt vector using #pragma interrupt, users can use portYIELD_FROM_ISR() without modifying the driver’s code by taking advantage of this mechanism, which does not require ISR wrappers.
• *4: Since context restoring is executed when portYIELD_FROM_ISR() is called, the system immediately switches to a task at the point where portYIELD_FROM_ISR() is called. Therefore, if portYIELD_FROM_ISR() is called in the middle of an interrupt handler’s processing, the remaining interrupt processing will be suspended.
• *5: In addition to the context saving, which is the compiler-generated code, executed at the time an interrupt occurs, another context saving operation occurs when portYIELD_FROM_ISR() is called. As a result, an interrupt handler that uses portYIELD_FROM_ISR() requires additional memory for the context saved at the time the interrupt occurs.

For version 11.1.0 or earlier

In these versions, the behavior is the same as when configREQUIRE_ASM_ISR_WRAPPER == 1 is set. Therefore, when there is an interrupt handler that calls portYIELD_FROM_ISR(), the user must implement an ISR wrapper for that handler.
Please modify the source code as follows so that configREQUIRE_ASM_ISR_WRAPPER can be used with these versions.

Target source file to be modified

• ./portable/Renesas/RL78/portmacro.h
• ./portable/Renesas/RL78G2x78/portmacro.h

Before modification

#define portYIELD_FROM_ISR( xHigherPriorityTaskWoken ) if( xHigherPriorityTaskWoken ) vTaskSwitchContext()

After modification

#ifndef configREQUIRE_ASM_ISR_WRAPPER
    #define configREQUIRE_ASM_ISR_WRAPPER    1
#endif
#if( configREQUIRE_ASM_ISR_WRAPPER == 1 )
    /* You must implement an assembly ISR wrapper (see the below for details) if you need an ISR to cause a context switch.
     * https://www.freertos.org/Documentation/02-Kernel/03-Supported-devices/04-Demos/Renesas/RTOS_RL78_IAR_Demos#writing-interrupt-service-routines */
    #define portYIELD_FROM_ISR( xHigherPriorityTaskWoken )    do { if( xHigherPriorityTaskWoken != pdFALSE ) vTaskSwitchContext(); } while( 0 )
#else
    /* You must not implement an assembly ISR wrapper even if you need an ISR to cause a context switch.
     * The portYIELD, which is similar to role of an assembly ISR wrapper, runs only when a context switch is required. */
    #define portYIELD_FROM_ISR( xHigherPriorityTaskWoken )    do { if( xHigherPriorityTaskWoken != pdFALSE ) portYIELD(); } while( 0 )
#endif