FreeRTOSのタスク制御API

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

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

システムコール及びAPI

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

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

vTaskStartScheduler

void vTaskStartScheduler( void )

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

vTaskEndScheduler

void vTaskEndScheduler( void )

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

xTaskGetTickCount

TickType_t xTaskGetTickCount( void )

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

task関連

xTaskCreate

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	タスク起動時にタスクに渡される引数。 基本的にはNULLで設定
	uxPriority	優先度
	pvCreatedTask	タスクのID
	返り値	タスク生成が成功ならばpdTRUEを返す

xTaskGetCurrentTaskHandle

TaskHandle_t xTaskGetCurrentTaskHandle( void )

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

vTaskDelete

void vTaskDelete( TaskHandle_t xTaskToDelete )

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

wake, sleep

wake(vTaskResume)
sleep(vTaskSuspend)

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

vTaskSuspend

void vTaskSuspend( TaskHandle_t xTaskToSuspend )

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

vTaskResume, xTaskResumeFromISR

void vTaskResume( TaskHandle_t xTaskToResume )
void xTaskResumeFromISR( TaskHandle_t xTaskToResume )

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

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

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

vTaskDelay

void vTaskDelay( const TickType_t xTicksToDelay )

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

vTaskDelayUntil

void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
                      const TickType_t xTimeIncrement )

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

xTaskAbortDelay

BaseType_t xTaskAbortDelay( TaskHandle_t xTask )

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

タスク通知

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

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

xTaskNotify

BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction )

xTaskGenericNotify

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

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

void *pvPortMalloc( size_t xSize )

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

vPortFree

void vPortFree( void *pv )

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