[OS] The way to adjust the total stack size of threads¶

Of Cortex-A9 CMSIS-RTOS RTX, I'll explain the total stack size adjustment method of thread.
In the current setting, we have 32Kbyte ensure the total stack size of the thread.
And I think that you can use it without any adjustments when you from past experience.
However, because there is a need to be adjusted case, please refer to the following.

When to Adjust¶

If any of the following occur, you may need to adjust the total stack size of the thread.

• Fail to generate the thread
  If osThreadCreate () return value is NULL, has failed to generate the thread.
  Total stack size lack of thread there is a possibility of cause.
  In this case, there is a need to increase the total stack size of the thread.
  
  
• RAM is insufficient, I want to scraping the stack size
  In the current setting of the mbed-rtos, and we have the total stack size = 32KB of thread.
  RAM is insufficient as a system, if you want to reduce the stack size to adjust the total stack size of the thread.
  
  
• Thread stack overflow
  If an error in the OS occurs during thread execution, os_error () ⇒mbed_die () is called.
  The following macro that you want to 1, LED1 ~ LED4 will blink, and you can check the error occurred.
  
  <<code title = (mbed-src Top)\libraries\mbed\targets\hal\TARGET_RENESAS\TARGET_RZ_A1H\device.h　 line 64>>
  　　　　
  1. define DEVICE_ERROR_PATTERN 0 　　　　 ⇒　#define DEVICE_ERROR_PATTERN 1 <</code>>
     If the above phenomenon occurs, there is a possibility that thread has caused a stack overflow.
     In this case, increase the stack size specified in osThreadDef (), please check whether the phenomenon is improved.
     To match the stack size was increased, you will also need to adjust the total stack size.
     
     
     

Adjustment method¶

Adjust target macro¶

The total stack size of the thread to be adjusted, are defined in the macro to the configurator file of the OS.
If you want to adjust the total stack size of the thread, you can modify the settings of the following macro.

     #define  OS_PRIVSTKSIZE 8192

In Cortex-A9 CMSIS-RTOS RTX, for the specification to ensure the stack size in word units, the total stack size of the thread will be secured 4 times the size OS_PRIVSTKSIZE.
In the above case, the total stack size is as follows.

 　Total stack size = OS_PRIVSTKSIZE * 4 = 8192 * 4 = 32Kbyte

Relationship of the total number of threads and total stack size¶

If you want to adjust the total number of threads, you can modify the settings of OS_PRIVCNT macro.
If the total number of threads, and that the total stack size is defined in the following,

#define  OS_PRIVCNT 　　10
#define  OS_PRIVSTKSIZE 10240

(Note:2015/1/12 time of mbed-rtos, making it the following respectively, but are described here to change the value)

　　　#define  OS_PRIVCNT 　　8
　　　#define  OS_PRIVSTKSIZE 8192

The total stack size is below:

 　Total stack size = OS_PRIVSTKSIZE * 4 = 10240 * 4 = 40Kbyte

The above total stack size 40Kbyte, I will Wakeai the number of threads that have defined in OS_PRIVCNT.
As a rule of thumb, the average stack size per thread Estimate as follows.

 　Total stack size / OS_PRIVCNT = 40Kbyte / 10 = 4Kbyte

Breakdown of the stack size of each thread can be freely set by the user.
In concrete on the source code, when you have defined a osThreadDef (), you can specify the stack size of the thread in the third argument.

osThreadDef(sample_thread, osPriorityNormal, 1024);
                                             ^^^^

For example, you can also set a 10 thread's stack as follows.

 Thread 1：　　　1 Kbyte
 Thread 2：　　　1 Kbyte
 Thread 3：　　　2 Kbyte
 Thread 4：　　　5 Kbyte
 Thread 5：　　 10 Kbyte
 Thread 6：　　 10 Kbyte
 Thread 7：　　　1 Kbyte
 Thread 8：　　　3 Kbyte
 Thread 9：　　　2 Kbyte
 Thread 10：　　 5 Kbyte
 --------------------------------
 sum　　　　 　 40 Kbyte

Future of the corresponding¶

In the Cortex-A9 and Cortex-M has the following difference to the specifications of the CMSIS-RTOS RTX.
In Cortex-M for CMSIS-RTOS RTX, but users will has become a may specification without considering the total stack size of the thread, and leave the adjustment of the total stack size of the thread to the user in CMSIS-RTOS RTX for Cortex-A9 making it the specification.
It is a policy to match the specifications of the Cortex-A9 to the specifications of the Cortex-M (in corresponding adjustment), but in the meantime, (at the time of shortage) total stack size adjustment of thread at the user side is required.

The following is the information about the OS difference.

[OS]スレッドの総スタックサイズ調整方法¶

Cortex-A9 CMSIS-RTOS RTXの、スレッドの総スタックサイズ調整方法を説明します。
現在の設定では、スレッドの総スタックサイズを32Kbyte確保しています。
過去実績からすると調整なしでお使い頂けると思います。
ただし、調整が必要なケースがありますので、以下をご参照ください。

調整が必要なケース¶

以下の現象が発生した場合、スレッドの総スタックサイズを調整する必要があります。

• スレッドの生成に失敗する
  osThreadCreate()戻り値がNULLの場合、スレッドの生成に失敗しています。
  スレッドの総スタックサイズ不足が原因の可能性があります。
  この場合、スレッドの総スタックサイズを増加させる必要があります。
  
  
• RAMが不足し、スタックサイズを削りたい
  現在のmbed-rtosの設定では、スレッドの総スタックサイズ = 32KBとしています。
  システムとしてRAMが不足し、スタックサイズを減らしたい場合はスレッドの総スタックサイズを調整します。
  
  
• スレッドのスタックオーバーフロー
  スレッド実行中にOS内でエラーが発生した場合、os_error()⇒mbed_die()がコールされます。
  以下のマクロを1にすることで、LED1～LED4が点滅し、エラー発生を確認できます。
  
  <<code title = (mbed-src Top)\libraries\mbed\targets\hal\TARGET_RENESAS\TARGET_RZ_A1H\device.h　 64行目>>
  　　　　
  1. define DEVICE_ERROR_PATTERN 0 　　　　 ⇒　#define DEVICE_ERROR_PATTERN 1 <</code>>
     上記現象が発生した場合、スレッドがスタックオーバーフローを起こした可能性があります。
     この場合、osThreadDef()にて指定したスタックサイズを増加させ、現象が改善するか確認ください。
     増加させたスタックサイズに合わせて、総スタックサイズも調整する必要があります。
     
     
     

調整方法¶

調整対象マクロ¶

調整対象となるスレッドの総スタックサイズは、OSのコンフィギュレータファイルにマクロで定義されています。
スレッドの総スタックサイズを調整する場合は、下記マクロの設定値を修正します。

     #define  OS_PRIVSTKSIZE 8192

Cortex-A9 CMSIS-RTOS RTXでは、ワード単位でスタックサイズを確保する仕様のため、スレッドの総スタックサイズはOS_PRIVSTKSIZE を4倍したサイズが確保されます。
上記の場合、総スタックサイズは、以下のようになります。

 　総スタックサイズ = OS_PRIVSTKSIZE * 4 = 8192 * 4 = 32Kbyte

総スレッド数と総スタックサイズの関係¶

総スレッド数を調整する場合は、OS_PRIVCNTマクロの設定値を修正します。
総スレッド数、および総スタックサイズを以下で定義した場合、

#define  OS_PRIVCNT 　　10
#define  OS_PRIVSTKSIZE 10240

(※2015/1/12時点のmbed-rtosでは、それぞれ以下となっていますが、ここでは値を変更して説明します。)

　　　#define  OS_PRIVCNT 　　8
　　　#define  OS_PRIVSTKSIZE 8192

総スタックサイズは、

 　総スタックサイズ = OS_PRIVSTKSIZE * 4 = 10240 * 4 = 40Kbyte

となります。
上記総スタックサイズ 40Kbyte を、OS_PRIVCNTにて定義したスレッド数で分け合います。
目安として、1スレッドあたりの平均スタックサイズは、以下のように見積もれます。

 　総スタックサイズ / OS_PRIVCNT = 40Kbyte / 10 = 4Kbyte

各スレッドのスタックサイズの内訳はユーザが自由に設定できます。
具体的にはソースコード上で、osThreadDef()を定義した際、第三引数でスレッドのスタックサイズを指定します。

osThreadDef(sample_thread, osPriorityNormal, 1024);
                                             ^^^^

例えば、以下のように10スレッドのスタックを設定することもできます。

 Thread 1：　　　1 Kbyte
 Thread 2：　　　1 Kbyte
 Thread 3：　　　2 Kbyte
 Thread 4：　　　5 Kbyte
 Thread 5：　　 10 Kbyte
 Thread 6：　　 10 Kbyte
 Thread 7：　　　1 Kbyte
 Thread 8：　　　3 Kbyte
 Thread 9：　　　2 Kbyte
 Thread 10：　　 5 Kbyte
 ――――――――――
合計　　　　 　 40 Kbyte

今後の対応¶

Cortex-A9とCortex-MとでCMSIS-RTOS RTXの仕様に以下の差分があります。
Cortex-M用 CMSIS-RTOS RTXでは、ユーザがスレッドの総スタックサイズを意識しないでよい仕様となっておりますが、Cortex-A9用 CMSIS-RTOS RTXではユーザにスレッドの総スタックサイズの調整を任せる仕様となっています。
Cortex-A9の仕様をCortex-Mの仕様に合わせる方針(対応調整中)ですが、それまでの間、ユーザ側でのスレッドの総スタックサイズ調整(不足時)が必要になります。

以下、OS差分に関する情報です。