FreeRTOSのタスク制御API


下記の記事から続くFreeRTOSの機能に関する記事です。

https://qiita.com/tom_S/items/ea653880132e1fcfed72

FreeRTOSのタスク制御に関わるAPIについて説明します。

# システムコール及びAPI

概ね使用頻度が高いものを重点的に説明する。「～ISR」という名前の付いた関数(xEventGroupSetBitsFromISR, xMessageBufferSendFromISR等 )は割込みのルーチンからシステムコール(セマフォ・イベントフラグ・メッセージボックス等の関数)を呼ぶ際に用いる関数である。

※ただし、この割込み用のシステムコールではシステムコールのアドレスを別の場所にストックし、割込み終了後にタイマー割り込みによって呼び出していると思われる。

## vTaskStartScheduler
```c
void vTaskStartScheduler( void )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | ----------------------------------------------------------------- |
| 機能 || スケジューラをスタートする。(RTOSの動作開始) |
| 引数 |  | なし |
|返り値|  | なし |

## vTaskEndScheduler
```c
void vTaskEndScheduler( void )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | ------------------------------ |
|機能|| スケジューラを停止する。(RTOSの動作終了) |
| 引数 | | なし |
|返り値| | なし |

## xTaskGetTickCount
```c
TickType_t xTaskGetTickCount( void )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | --------------------------------- |
|機能|| OSのスケジューラで使用するタイマの値を取得する |
| 引数 | | なし |
|返り値| | OSのタイマの値 |

## task関連

### xTaskCreate
```c
BaseType_t xTaskCreate( TaskFunction_t pvTaskCode,
                        const char * const pcName,
                        configSTACK_DEPTH_TYPE usStackDepth,
                        void *pvParameters,
                        UBaseType_t uxPriority,
                        TaskHandle_t *pvCreatedTask )
```

|  項目1  |    項目2    | 説明 |
| ------------- |  -------------------- | -------------------- |
| 機能 |              |タスクを生成する。|
| 引数 | pvTaskCode   | タスクとなる関数 |
|     | pcName       | タスク名(デバッグ用。動作に影響なし) |
|     | usStackDepth | スタックサイズ |
|     | pvParameters | タスク起動時にタスクに渡される引数。<br>基本的にはNULLで設定 |
|     | uxPriority   | 優先度 |
|     | pvCreatedTask | タスクのID |
|     | 返り値         | タスク生成が成功ならばpdTRUEを返す |

### xTaskGetCurrentTaskHandle
```c
TaskHandle_t xTaskGetCurrentTaskHandle( void )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | -------------------------------- |
| 機能 |  | 呼び出し先のタスクのIDを取得する |
| 引数 | | なし  |
| 返り値 | | 呼び出し先のタスクID |

### vTaskDelete
```c
void vTaskDelete( TaskHandle_t xTaskToDelete )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | -------------------------------- |
| 機能 |  | タスクを削除する(タスクがsuspendedステート、blockedステートの際に動作可能) |
| 引数 | xTaskToDelete | 削除するタスクのID。NULLを指定した場合は、呼び出し元のタスクが指定されたことになる |
| 返り値 | | なし |


## wake, sleep
```c
wake(vTaskResume)
sleep(vTaskSuspend)
```

wake,sleepという概念はなく、sleepはvTaskSuspend() 、wakeはvTaskResume() で代用することになる。ただし、vTaskResume()が呼ばれた後にvTaskSuspend()が呼ばれた際は、初めに呼ばれたvTaskResume()は無効になる。使用する際は必ずvTaskSuspend()を呼んだ後にvTaskResume()を呼ぶ必要がある(つまり、itronと違い、wakeリクエストはキューイングされない)

### vTaskSuspend
```c
void vTaskSuspend( TaskHandle_t xTaskToSuspend )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | -------------------------------- |
| 機能 |  |タスクのステートをSuspendedステートへ変更する |
| 引数 | xTaskToSuspend | Suspendedステートへステートを変更する対象のタスクID。NULLを指定した場合は、呼び出し元のタスクが指定されたことになる |
| 返り値 | | なし |


### vTaskResume, xTaskResumeFromISR
```c
void vTaskResume( TaskHandle_t xTaskToResume )
void xTaskResumeFromISR( TaskHandle_t xTaskToResume )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | ---------------------------------------------- |
| 機能 |  |Suspendedステートのタスク<br>のステートをReadyステート<br>へ変更する。このとき、指定<br>したIDのタスクがSuspended<br>ステートでない場合は何もしない |
| 引数 | xTaskToSuspend | Readyステートへステートを<br>変更する対象のタスクID |
| 返り値 | | なし |


## タスクの一定時間の休止(vTaskDelay, vTaskDelayUntil)

「FreeRTOSConfig.h」の「configTICK_RATE_HZ」の値によって精度が変わるので注意。ms単位でwait,delayをしたい場合は、「configTICK_RATE_HZ」の値を1000にすること

### vTaskDelay
```c
void vTaskDelay( const TickType_t xTicksToDelay )
```

| 項目1 |  項目2 | 説明 |
| ------------- | ------------- | ------------------------------------------ |
| 機能 |  | 呼び出し先のタスクを引数で<br>指定した時間waitする |
| 引数 | xTicksToDelay | waitする時間 |
| 返り値 |  | なし |

### vTaskDelayUntil
```c
void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
                      const TickType_t xTimeIncrement )
```

| 項目1 |  項目2 | 説明 |
| ------------- | ---------------------- | ------------------------------------------------ |
| 機能 |  | 呼び出し先のタスクを指定した時間<br>(pxPreviousWakeTime + xTimeIncrement )<br>までwaitする。周期タスクにて使用するの<br>がよい。vTaskDelayは、関数が呼ばれた時<br>点から指定した時間waitするが、この関数<br>はpxPreviousWakeTimeで入力された時間<br>から、xTimeIncrement <br>で指定した時間waitする |
| 引数 | pxPreviousWakeTime | waitする時間の基準となる値。<br>初回の呼び出し時はxTaskGetTickCount()<br>で取得した時間を入れる。<br>関数内でwaitが終了した時点で<br>pxPreviousWakeTime <br>= pxPreviousWakeTime <br>+ xTimeIncrement <br> に更新される |
|  | xTimeIncrement | pxPreviousWakeTimeからwaitする時間 |
|返り値| | なし |

### xTaskAbortDelay
```c
BaseType_t xTaskAbortDelay( TaskHandle_t xTask )
```

| 項目1 |  項目2 | 説明 |
| ------------- | ------------- | ------------------------------------------ |
| 機能 |  | delayしているタスクを強制的にReady状態(実行可能状態)にする |
| 引数 | xTask | delayを解除したいタスクID |
| 返り値 |  | 指定したタスクがReady状態にできたらpdTRUEを返す |

## タスク通知

セマフォやストリームバッファのように、他のタスクへ通知を行う際にオブジェクト仲介せず、
直接他のタスクへ通知を行う。xTaskNotifyWait()で通知待ちを行い、xTaskNotify()で通知をする。

また、xTaskNotifyWait()で通知待ちを行う前にxTaskNotify()を呼び出した場合は、
xTaskNotify()で通知された値が保存されており、xTaskNotifyWait()は待ち時間なしで通知された値を受け取り、リターンされる。

### xTaskNotify
```c
BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction )
```

### xTaskGenericNotify
```c
BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue )
```

| 項目1 |  項目2 | 説明 |
| ------------- | ------------- | ------------------------------------------ |
| 機能 |  | タスクの通知を行う |
| 引数 | xTaskToNotify | 通知するタスクの管理構造体 |
| 引数 | ulValue | 通知する値 |
| 引数 | eAction | 通知オプション |
| 引数 | pulPreviousNotificationValue | 一つ前に通知された値を代入する変数のポインタ |
| 返り値 |  | 正常終了ならばpdTRUE |

eActionに設定される値は下記の通り
| 値 | 説明 |
| ------------- | ------------------------------------------ |
| eNoAction | 値は通知しない |
| eSetBits | 通知用の値にORを取る |
| eIncrement | 通知用の値をインクリメントする(ulValueは無視される) |
| eSetValueWithOverwrite | 一つ前の通知用の値が読みだされている/いないに関わらず、通知用の値を更新 |
| eSetValueWithoutOverwrite | 一つ前の通知用の値が読みだされていない場合は通知せず、返り値をpdFALSEを返す |

### xTaskNotifyWait
```c
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait )
```

| 項目1 |  項目2 | 説明 |
| ------------- | ------------- | ------------------------------------------ |
| 機能 |  | 他のタスクからの通知待ちを行う |
| 引数 | ulBitsToClearOnEntry | 通知前にこの関数が呼び出された際に、 ( 一つ前の通知された値 ) XOR ulBitsToClearOnEntryを行う。pulNotificationValueに代入する |
|  | ulBitsToClearOnExit | 通知前にこの関数が呼び出された際に、 ( 一つ前の通知された値 ) XOR ulBitsToClearOnEntryを行う。pulNotificationValueの示す値には反映されない。 |
|  | pulNotificationValue | 通知された値を格納する変数のポインタ。実体はユーザで定義する |
|  | xTicksToWait | タイムアウト時間。タイムアウトを無しに設定する場合は、FreeRTOSConfig.hにて「INCLUDE_vTaskSuspend」を1に定義し、xTicksToWaitはportMAX_DELAYを指定する。 |
| 返り値 |  | 正常終了ならばpdTRUE |


## メモリ関連

### pvPortMalloc
```c
void *pvPortMalloc( size_t xSize )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | ----------------------------------------------------------------- |
|機能|| メモリの確保 |
| 引数 | xSize | 確保するメモリサイズ |
|返り値| | 確保したメモリの先頭ポインタ |


### vPortFree
```c
void vPortFree( void *pv )
```

| 項目1 |  項目2 | 説明 |
| ------------- |  ------------- | ----------------------------------------------------------------- |
|機能|| メモリの解放 |
| 引数 | pv | 解放するメモリの先頭ポインタ |
|返り値| | なし |