//作用：包含任務管理的程式碼，使用OSTaskCreate()，OSTaskDel()，OSTaskChangePrio()等函式實現；
/*
*********************************************************************************************************
* uC/OS-III
* The Real-Time Kernel
*
* Copyright 2009-2022 Silicon Laboratories Inc. www.silabs.com
*
* SPDX-License-Identifier: APACHE-2.0
*
* This software is subject to an open source license and is distributed by
* Silicon Laboratories Inc. pursuant to the terms of the Apache License,
* Version 2.0 available at www.apache.org/licenses/LICENSE-2.0.
*
*********************************************************************************************************
*/
/*
*********************************************************************************************************
* TASK MANAGEMENT
*
* File : os_task.c
* Version : V3.08.02
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#include "os.h"
#ifdef VSC_INCLUDE_SOURCE_FILE_NAMES
const CPU_CHAR *os_task__c = "$Id: $";
#endif
/*
************************************************************************************************************************
* CHANGE PRIORITY OF A TASK
*
* Description: This function allows you to change the priority of a task dynamically. Note that the new
* priority MUST be available.
*
* Arguments : p_tcb is the TCB of the tack to change the priority for
*
* prio_new is the new priority
*
* p_err is a pointer to an error code returned by this function:
*
* OS_ERR_NONE Is the call was successful
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_PRIO_INVALID If the priority you specify is higher that the maximum allowed
* (i.e. >= (OS_CFG_PRIO_MAX-1)) or already in use by a kernel
* task
* OS_ERR_STATE_INVALID If the task is in an invalid state
* OS_ERR_TASK_CHANGE_PRIO_ISR If you tried to change the task's priority from an ISR
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_CHANGE_PRIO_EN > 0u)
// 修改任務的優先順序
void OSTaskChangePrio(OS_TCB *p_tcb,
OS_PRIO prio_new,
OS_ERR *p_err)
{
#if (OS_CFG_MUTEX_EN > 0u)
OS_PRIO prio_high;
#endif
CPU_SR_ALLOC(); // 分配CPU狀態暫存器
#ifdef OS_SAFETY_CRITICAL
// 在安全關鍵應用中，檢查錯誤引數是否為空
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if (OS_CFG_ARG_CHK_EN > 0u)
// 檢查任務控制塊指標是否有效，並且任務狀態不是刪除
if ((p_tcb != (OS_TCB *)0) && (p_tcb->TaskState == OS_TASK_STATE_DEL))
{
*p_err = OS_ERR_STATE_INVALID;
return;
}
#endif
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
// 檢查是否在中斷服務程式中呼叫，不允許在中斷中改變任務優先順序
if (OSIntNestingCtr > 0u)
{
*p_err = OS_ERR_TASK_CHANGE_PRIO_ISR;
return;
}
#endif
// 檢查新優先順序是否有效，不能設定為閒置任務的優先順序
if (prio_new >= (OS_CFG_PRIO_MAX - 1u))
{
*p_err = OS_ERR_PRIO_INVALID;
return;
}
CPU_CRITICAL_ENTER(); // 進入臨界區
// 如果任務控制塊指標為空，表示要修改當前任務的優先順序
if (p_tcb == (OS_TCB *)0)
{
if (OSRunning != OS_STATE_OS_RUNNING)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_OS_NOT_RUNNING;
return;
}
p_tcb = OSTCBCurPtr;
}
#if (OS_CFG_MUTEX_EN > 0u)
// 更新任務的基礎優先順序
p_tcb->BasePrio = prio_new;
// 如果任務持有互斥訊號量，需要進行優先順序繼承的處理
if (p_tcb->MutexGrpHeadPtr != (OS_MUTEX *)0)
{
if (prio_new > p_tcb->Prio)
{
prio_high = OS_MutexGrpPrioFindHighest(p_tcb);
if (prio_new > prio_high)
{
prio_new = prio_high;
}
}
}
#endif
// 呼叫核心函式修改任務優先順序
OS_TaskChangePrio(p_tcb, prio_new);
// 跟蹤任務優先順序改變
OS_TRACE_TASK_PRIO_CHANGE(p_tcb, prio_new);
CPU_CRITICAL_EXIT(); // 退出臨界區
// 如果作業系統正在執行，進行任務排程
if (OSRunning == OS_STATE_OS_RUNNING)
{
OSSched();
}
*p_err = OS_ERR_NONE; // 設定無錯誤
}
#endif
/*
************************************************************************************************************************
* CREATE A TASK
*
* Description: This function is used to have uC/OS-III manage the execution of a task. Tasks can either be created
* prior to the start of multitasking or by a running task. A task cannot be created by an ISR.
*
* Arguments : p_tcb is a pointer to the task's TCB
*
* p_name is a pointer to an ASCII string to provide a name to the task.
*
* p_task is a pointer to the task's code
*
* p_arg is a pointer to an optional data area which can be used to pass parameters to
* the task when the task first executes. Where the task is concerned it thinks
* it was invoked and passed the argument 'p_arg' as follows:
*
* void Task (void *p_arg)
* {
* for (;;) {
* Task code;
* }
* }
*
* prio is the task's priority. A unique priority MUST be assigned to each task and the
* lower the number, the higher the priority.
*
* p_stk_base is a pointer to the base address of the stack (i.e. low address).
*
* stk_limit is the number of stack elements to set as 'watermark' limit for the stack. This value
* represents the number of CPU_STK entries left before the stack is full. For example,
* specifying 10% of the 'stk_size' value indicates that the stack limit will be reached
* when the stack reaches 90% full.
*
* stk_size is the size of the stack in number of elements. If CPU_STK is set to CPU_INT08U,
* 'stk_size' corresponds to the number of bytes available. If CPU_STK is set to
* CPU_INT16U, 'stk_size' contains the number of 16-bit entries available. Finally, if
* CPU_STK is set to CPU_INT32U, 'stk_size' contains the number of 32-bit entries
* available on the stack.
*
* q_size is the maximum number of messages that can be sent to the task
*
* time_quanta amount of time (in ticks) for time slice when round-robin between tasks. Specify 0 to use
* the default.
*
* p_ext is a pointer to a user supplied memory location which is used as a TCB extension.
* For example, this user memory can hold the contents of floating-point registers
* during a context switch, the time each task takes to execute, the number of times
* the task has been switched-in, etc.
*
* opt contains additional information (or options) about the behavior of the task.
* See OS_OPT_TASK_xxx in OS.H. Current choices are:
*
* OS_OPT_TASK_NONE No option selected
* OS_OPT_TASK_STK_CHK Stack checking to be allowed for the task
* OS_OPT_TASK_STK_CLR Clear the stack when the task is created
* OS_OPT_TASK_SAVE_FP If the CPU has floating-point registers, save them
* during a context switch.
* OS_OPT_TASK_NO_TLS If the caller doesn't want or need TLS (Thread Local
* Storage) support for the task. If you do not include this
* option, TLS will be supported by default.
*
* p_err is a pointer to an error code that will be set during this call. The value pointer
* to by 'p_err' can be:
*
* OS_ERR_NONE If the function was successful
* OS_ERR_ILLEGAL_CREATE_RUN_TIME If you are trying to create the task after you called
* OSSafetyCriticalStart()
* OS_ERR_PRIO_INVALID If the priority you specify is higher that the maximum
* allowed (i.e. >= OS_CFG_PRIO_MAX-1) or,
* OS_ERR_STK_OVF If the stack was overflowed during stack init
* OS_ERR_STK_INVALID If you specified a NULL pointer for 'p_stk_base'
* OS_ERR_STK_SIZE_INVALID If you specified zero for the 'stk_size'
* OS_ERR_STK_LIMIT_INVALID If you specified a 'stk_limit' greater than or equal
* to 'stk_size'
* OS_ERR_TASK_CREATE_ISR If you tried to create a task from an ISR
* OS_ERR_TASK_INVALID If you specified a NULL pointer for 'p_task'
* OS_ERR_TCB_INVALID If you specified a NULL pointer for 'p_tcb'
*
* Returns : none
*
* Note(s) : 1) OSTaskCreate() will return with the error OS_ERR_STK_OVF when a stack overflow is detected
* during stack initialization. In that specific case some memory may have been corrupted. It is
* therefore recommended to treat OS_ERR_STK_OVF as a fatal error.
************************************************************************************************************************
*/
/**
* 建立一個作業系統任務。
*
* @param p_tcb 指向任務控制塊(TCB)的指標，用於儲存任務的控制資訊。
* @param p_name 指向任務名稱的字串指標，用於標識任務。
* @param p_task 指向任務入口函式的指標，即任務開始執行的地方。
* @param p_arg 指向任務引數的指標，這個引數將傳遞給任務入口函式。
* @param prio 任務的優先順序，決定了任務的執行順序和排程行為。
* @param p_stk_base 指向任務棧底的指標，用於分配任務的執行棧。
* @param stk_limit 任務棧的最小大小，用於棧溢位檢測。
* @param stk_size 任務棧的總大小，用於分配給任務的棧空間。
* @param q_size 任務訊息佇列的大小，決定了任務可以接收的訊息數量。
* @param time_quanta 任務的時間片大小，用於輪轉排程演算法。
* @param p_ext 指向任務擴充套件資訊的指標，用於儲存額外的任務特定資訊。
* @param opt 任務建立選項，用於指定任務的特殊行為和屬性。
* @param p_err 指向錯誤程式碼的指標，用於返回任務建立過程中的錯誤資訊。
*
* 此函式用於在實時作業系統(RTOS)中建立一個新的任務。任務是作業系統排程的基本單位，
* 具有自己的執行環境和上下文。透過這個函式，使用者可以定義任務的行為、所需的資源以及
* 如何與其他任務互動。任務一旦建立，將由作業系統根據排程策略進行管理和排程。
*/
void OSTaskCreate(OS_TCB *p_tcb,
CPU_CHAR *p_name,
OS_TASK_PTR p_task,
void *p_arg,
OS_PRIO prio,
CPU_STK *p_stk_base,
CPU_STK_SIZE stk_limit,
CPU_STK_SIZE stk_size,
OS_MSG_QTY q_size,
OS_TICK time_quanta,
void *p_ext,
OS_OPT opt,
OS_ERR *p_err)
{
CPU_STK_SIZE i;
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
OS_REG_ID reg_nbr;
#endif
#if defined(OS_CFG_TLS_TBL_SIZE) && (OS_CFG_TLS_TBL_SIZE > 0u)
OS_TLS_ID id;
#endif
CPU_STK *p_sp;
CPU_STK *p_stk_limit;
CPU_SR_ALLOC();
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE)
{
*p_err = OS_ERR_ILLEGAL_CREATE_RUN_TIME;
return;
}
#endif
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* 不能從中斷服務例程(ISR)中建立任務 */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_TASK_CREATE_ISR;
return;
}
#endif
#if (OS_CFG_ARG_CHK_EN > 0u) /* 驗證引數 */
if (p_tcb == (OS_TCB *)0)
{ /* 使用者必須提供有效的任務控制塊(TCB) */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_TCB_INVALID;
return;
}
if (p_task == (OS_TASK_PTR)0u)
{ /* 使用者必須提供有效的任務入口函式 */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_TASK_INVALID;
return;
}
if (p_stk_base == (CPU_STK *)0)
{ /* 使用者必須提供有效的棧基地址 */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_STK_INVALID;
return;
}
if (stk_size < OSCfg_StkSizeMin)
{ /* 使用者必須提供有效的最小棧大小 */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_STK_SIZE_INVALID;
return;
}
if (stk_limit >= stk_size)
{ /* 使用者必須提供有效的棧限制 */
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_STK_LIMIT_INVALID;
return;
}
if ((prio > (OS_CFG_PRIO_MAX - 2u)) && /* 優先順序必須在0和OS_CFG_PRIO_MAX-1之間 */
(prio != (OS_CFG_PRIO_MAX - 1u)))
{
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_PRIO_INVALID;
return;
}
#endif
if (prio == (OS_CFG_PRIO_MAX - 1u))
{
#if (OS_CFG_TASK_IDLE_EN > 0u)
if (p_tcb != &OSIdleTaskTCB)
{
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_PRIO_INVALID; /* 不允許使用與空閒任務相同的優先順序 */
return;
}
#else
OS_TRACE_TASK_CREATE_FAILED(p_tcb);
*p_err = OS_ERR_PRIO_INVALID; /* 不允許使用與空閒任務相同的優先順序 */
return;
#endif
}
OS_TaskInitTCB(p_tcb); /* 初始化TCB為預設值 */
*p_err = OS_ERR_NONE;
/* 清除任務的棧 */
if (((opt & OS_OPT_TASK_STK_CHK) != 0u) || /* 檢查是否啟用了棧檢查 */
((opt & OS_OPT_TASK_STK_CLR) != 0u))
{ /* 檢查是否需要清除棧 */
if ((opt & OS_OPT_TASK_STK_CLR) != 0u)
{
p_sp = p_stk_base;
for (i = 0u; i < stk_size; i++)
{ /* 棧從高記憶體向低記憶體增長 */
*p_sp = 0u; /* 從棧底開始清零 */
p_sp++;
}
}
}
/* 初始化任務的棧幀 */
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO)
p_stk_limit = p_stk_base + stk_limit;
#else
p_stk_limit = p_stk_base + (stk_size - 1u) - stk_limit;
#endif
p_sp = OSTaskStkInit(p_task,
p_arg,
p_stk_base,
p_stk_limit,
stk_size,
opt);
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO) /* 檢查初始化過程中是否棧溢位 */
if (p_sp < p_stk_base)
{
*p_err = OS_ERR_STK_OVF;
return;
}
#else
if (p_sp > (p_stk_base + stk_size))
{
*p_err = OS_ERR_STK_OVF;
return;
}
#endif
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u) /* 初始化帶有紅區的棧 */
OS_TaskStkRedzoneInit(p_stk_base, stk_size);
#endif
/* 初始化TCB欄位 */
#if (OS_CFG_DBG_EN > 0u)
p_tcb->TaskEntryAddr = p_task; /* 儲存任務入口地址 */
p_tcb->TaskEntryArg = p_arg; /* 儲存任務入口引數 */
#endif
#if (OS_CFG_DBG_EN > 0u)
p_tcb->NamePtr = p_name; /* 儲存任務名稱 */
#else
(void)p_name;
#endif
p_tcb->Prio = prio; /* 儲存任務的優先順序 */
#if (OS_CFG_MUTEX_EN > 0u)
p_tcb->BasePrio = prio; /* 設定基礎優先順序 */
#endif
p_tcb->StkPtr = p_sp; /* 儲存新的棧頂指標 */
p_tcb->StkLimitPtr = p_stk_limit; /* 儲存棧限制指標 */
#if (OS_CFG_SCHED_ROUND_ROBIN_EN > 0u)
p_tcb->TimeQuanta = time_quanta; /* 儲存時間片的滴答數（0表示不切片） */
if (time_quanta == 0u)
{
p_tcb->TimeQuantaCtr = OSSchedRoundRobinDfltTimeQuanta;
}
else
{
p_tcb->TimeQuantaCtr = time_quanta;
}
#else
(void)time_quanta;
#endif
p_tcb->ExtPtr = p_ext; /* 儲存TCB擴充套件指標 */
#if ((OS_CFG_DBG_EN > 0u) || (OS_CFG_STAT_TASK_STK_CHK_EN > 0u) || (OS_CFG_TASK_STK_REDZONE_EN > 0u))
p_tcb->StkBasePtr = p_stk_base; /* 儲存棧基地址指標 */
p_tcb->StkSize = stk_size; /* 儲存棧大小（以CPU_STK元素為單位） */
#endif
p_tcb->Opt = opt; /* 儲存任務選項 */
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
for (reg_nbr = 0u; reg_nbr < OS_CFG_TASK_REG_TBL_SIZE; reg_nbr++)
{
p_tcb->RegTbl[reg_nbr] = 0u;
}
#endif
#if (OS_CFG_TASK_Q_EN > 0u)
OS_MsgQInit(&p_tcb->MsgQ, /* 初始化任務的訊息佇列 */
q_size);
#else
(void)q_size;
#endif
OSTaskCreateHook(p_tcb); /* 呼叫使用者定義的鉤子 */
OS_TRACE_TASK_CREATE(p_tcb);
OS_TRACE_TASK_SEM_CREATE(p_tcb, p_name);
#if (OS_CFG_TASK_Q_EN > 0u)
OS_TRACE_TASK_MSG_Q_CREATE(&p_tcb->MsgQ, p_name);
#endif
#if defined(OS_CFG_TLS_TBL_SIZE) && (OS_CFG_TLS_TBL_SIZE > 0u)
for (id = 0u; id < OS_CFG_TLS_TBL_SIZE; id++)
{
p_tcb->TLS_Tbl[id] = 0u;
}
OS_TLS_TaskCreate(p_tcb); /* 呼叫TLS鉤子 */
#endif
/* 將任務新增到就緒列表 */
CPU_CRITICAL_ENTER();
OS_PrioInsert(p_tcb->Prio);
OS_RdyListInsertTail(p_tcb);
#if (OS_CFG_DBG_EN > 0u)
OS_TaskDbgListAdd(p_tcb);
#endif
OSTaskQty++; /* 增加任務計數器 */
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* 如果多工尚未啟動則返回 */
CPU_CRITICAL_EXIT();
return;
}
CPU_CRITICAL_EXIT();
OSSched();
}
/*
************************************************************************************************************************
* DELETE A TASK
*
* Description: This function allows you to delete a task. The calling task can delete itself by specifying a NULL
* pointer for 'p_tcb'. The deleted task is returned to the dormant state and can be re-activated by
* creating the deleted task again.
*
* Arguments : p_tcb is the TCB of the tack to delete
*
* p_err is a pointer to an error code returned by this function:
*
* OS_ERR_NONE If the call is successful
* OS_ERR_ILLEGAL_DEL_RUN_TIME If you are trying to delete the task after you called
* OSStart()
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_STATE_INVALID If the state of the task is invalid
* OS_ERR_TASK_DEL_IDLE If you attempted to delete uC/OS-III's idle task
* OS_ERR_TASK_DEL_INVALID If you attempted to delete uC/OS-III's ISR handler task
* OS_ERR_TASK_DEL_ISR If you tried to delete a task from an ISR
*
* Returns : none
*
* Note(s) : 1) 'p_err' gets set to OS_ERR_NONE before OSSched() to allow the returned err or code to be monitored even
* for a task that is deleting itself. In this case, 'p_err' MUST point to a global variable that can be
* accessed by another task.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_DEL_EN > 0u)
void OSTaskDel(OS_TCB *p_tcb,
OS_ERR *p_err)
{
#if (OS_CFG_MUTEX_EN > 0u)
OS_TCB *p_tcb_owner;
OS_PRIO prio_new;
#endif
CPU_SR_ALLOC();
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE)
{
*p_err = OS_ERR_ILLEGAL_DEL_RUN_TIME;
return;
}
#endif
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* See if trying to delete from ISR */
*p_err = OS_ERR_TASK_DEL_ISR;
return;
}
#endif
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
*p_err = OS_ERR_OS_NOT_RUNNING;
return;
}
#endif
#if (OS_CFG_TASK_IDLE_EN > 0u)
if (p_tcb == &OSIdleTaskTCB)
{ /* Not allowed to delete the idle task */
*p_err = OS_ERR_TASK_DEL_IDLE;
return;
}
#endif
if (p_tcb == (OS_TCB *)0)
{ /* 刪除當前任務? */
CPU_CRITICAL_ENTER();
p_tcb = OSTCBCurPtr; /* 是，刪除當前任務 */
CPU_CRITICAL_EXIT();
}
CPU_CRITICAL_ENTER();
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
OS_RdyListRemove(p_tcb); /* 從就緒列表中移除任務 */
break;
case OS_TASK_STATE_SUSPENDED:
break; /* 暫停狀態無需操作 */
case OS_TASK_STATE_DLY: /* 任務僅被延遲，不在任何等待列表中 */
case OS_TASK_STATE_DLY_SUSPENDED:
#if (OS_CFG_TICK_EN > 0u)
OS_TickListRemove(p_tcb); /* 從時鐘列表中移除任務 */
#endif
break;
case OS_TASK_STATE_PEND:
case OS_TASK_STATE_PEND_SUSPENDED:
case OS_TASK_STATE_PEND_TIMEOUT:
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
switch (p_tcb->PendOn)
{ /* 檢查任務掛起的原因 */
case OS_TASK_PEND_ON_NOTHING:
case OS_TASK_PEND_ON_TASK_Q: /* 這兩種情況下沒有等待列表 */
case OS_TASK_PEND_ON_TASK_SEM:
break;
case OS_TASK_PEND_ON_FLAG: /* 從掛起列表中移除任務 */
case OS_TASK_PEND_ON_Q:
case OS_TASK_PEND_ON_SEM:
OS_PendListRemove(p_tcb);
break;
#if (OS_CFG_MUTEX_EN > 0u)
case OS_TASK_PEND_ON_MUTEX:
p_tcb_owner = ((OS_MUTEX *)((void *)p_tcb->PendObjPtr))->OwnerTCBPtr;
prio_new = p_tcb_owner->Prio;
OS_PendListRemove(p_tcb);
if ((p_tcb_owner->Prio != p_tcb_owner->BasePrio) &&
(p_tcb_owner->Prio == p_tcb->Prio))
{ /* 檢查是否繼承了優先順序 */
prio_new = OS_MutexGrpPrioFindHighest(p_tcb_owner);
prio_new = (prio_new > p_tcb_owner->BasePrio) ? p_tcb_owner->BasePrio : prio_new;
}
p_tcb->PendOn = OS_TASK_PEND_ON_NOTHING;
if (prio_new != p_tcb_owner->Prio)
{
OS_TaskChangePrio(p_tcb_owner, prio_new); /* 更改任務優先順序 */
OS_TRACE_MUTEX_TASK_PRIO_DISINHERIT(p_tcb_owner, p_tcb_owner->Prio);
}
break;
#endif
default:
break; /* 預設情況 */
}
#if (OS_CFG_TICK_EN > 0u)
if ((p_tcb->TaskState == OS_TASK_STATE_PEND_TIMEOUT) ||
(p_tcb->TaskState == OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED))
{
OS_TickListRemove(p_tcb); /* 從時鐘列表中移除任務 */
}
#endif
break;
default:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_STATE_INVALID; /* 無效的狀態 */
return;
}
#if (OS_CFG_MUTEX_EN > 0u)
if (p_tcb->MutexGrpHeadPtr != (OS_MUTEX *)0)
{
OS_MutexGrpPostAll(p_tcb); /* 釋放所有互斥量組 */
}
#endif
#if (OS_CFG_TASK_Q_EN > 0u)
(void)OS_MsgQFreeAll(&p_tcb->MsgQ); /* 釋放任務的訊息佇列訊息 */
#endif
OSTaskDelHook(p_tcb); /* 呼叫使用者定義的鉤子函式 */
#if defined(OS_CFG_TLS_TBL_SIZE) && (OS_CFG_TLS_TBL_SIZE > 0u)
OS_TLS_TaskDel(p_tcb); /* 呼叫TLS鉤子 */
#endif
#if (OS_CFG_DBG_EN > 0u)
OS_TaskDbgListRemove(p_tcb); /* 從除錯列表中移除任務 */
#endif
OSTaskQty--; /* 管理的任務數量減一 */
OS_TRACE_TASK_DEL(p_tcb); /* 記錄任務刪除事件 */
#if (OS_CFG_TASK_STK_REDZONE_EN == 0u) /* 在檢查紅區之前不清除TCB */
OS_TaskInitTCB(p_tcb); /* 初始化TCB為預設值 */
#endif
p_tcb->TaskState = (OS_STATE)OS_TASK_STATE_DEL; /* 標記任務已刪除 */
*p_err = OS_ERR_NONE; /* 設定錯誤碼為無錯誤 */
CPU_CRITICAL_EXIT();
OSSched(); /* 查詢新的最高優先順序任務 */
}
#endif
/*
************************************************************************************************************************
* FLUSH TASK's QUEUE
*
* Description: This function is used to flush the task's internal message queue.
*
* Arguments : p_tcb is a pointer to the task's OS_TCB. Specifying a NULL pointer indicates that you wish to
* flush the message queue of the calling task.
*
* p_err is a pointer to a variable that will contain an error code returned by this function.
*
* OS_ERR_NONE Upon success
* OS_ERR_FLUSH_ISR If you called this function from an ISR
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
*
* Returns : The number of entries freed from the queue
*
* Note(s) : 1) You should use this function with great care because, when to flush the queue, you LOOSE the
* references to what the queue entries are pointing to and thus, you could cause 'memory leaks'. In
* other words, the data you are pointing to that's being referenced by the queue entries should, most
* likely, need to be de-allocated (i.e. freed).
************************************************************************************************************************
*/
#if (OS_CFG_TASK_Q_EN > 0u)
// 函式OSTaskQFlush用於清空指定任務的訊息佇列
// 引數p_tcb: 指向任務控制塊的指標，用於標識需要清空訊息佇列的任務
// 引數p_err: 指向錯誤程式碼的指標，用於返回函式執行過程中的錯誤資訊
// 返回值: 返回被清空的訊息佇列中的訊息數量
OS_MSG_QTY OSTaskQFlush(OS_TCB *p_tcb,
OS_ERR *p_err)
{
OS_MSG_QTY entries;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保p_err引數不為NULL
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
// 檢查是否在中斷服務程式中呼叫：不允許在中斷中清空訊息佇列
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* Can't flush a message queue from an ISR */
*p_err = OS_ERR_FLUSH_ISR;
return (0u);
}
#endif
// 檢查核心是否正在執行：確保在核心執行時呼叫該函式
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
*p_err = OS_ERR_OS_NOT_RUNNING;
return (0u);
}
#endif
// 檢查p_tcb是否為NULL：如果為NULL，則清空當前任務的訊息佇列
if (p_tcb == (OS_TCB *)0)
{ /* Flush message queue of calling task? */
CPU_CRITICAL_ENTER();
p_tcb = OSTCBCurPtr;
CPU_CRITICAL_EXIT();
}
// 清空訊息佇列並將所有訊息返回到訊息池
CPU_CRITICAL_ENTER();
entries = OS_MsgQFreeAll(&p_tcb->MsgQ); /* Return all OS_MSGs to the OS_MSG pool */
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_NONE;
return (entries);
}
#endif
/*
************************************************************************************************************************
* WAIT FOR A MESSAGE
*
* Description: This function causes the current task to wait for a message to be posted to it.
*
* Arguments : timeout is an optional timeout period (in clock ticks). If non-zero, your task will wait for a
* message to arrive up to the amount of time specified by this argument.
* If you specify 0, however, your task will wait forever or, until a message arrives.
*
* opt determines whether the user wants to block if the task's queue is empty or not:
*
* OS_OPT_PEND_BLOCKING
* OS_OPT_PEND_NON_BLOCKING
*
* p_msg_size is a pointer to a variable that will receive the size of the message
*
* p_ts is a pointer to a variable that will receive the timestamp of when the message was
* received. If you pass a NULL pointer (i.e. (CPU_TS *)0) then you will not get the
* timestamp. In other words, passing a NULL pointer is valid and indicates that you don't
* need the timestamp.
*
* p_err is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE The call was successful and your task received a message.
* OS_ERR_OPT_INVALID If you specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_PEND_ABORT If the pend was aborted
* OS_ERR_PEND_ISR If you called this function from an ISR and the result
* OS_ERR_PEND_WOULD_BLOCK If you specified non-blocking but the queue was not empty
* OS_ERR_PTR_INVALID If 'p_msg_size' is NULL
* OS_ERR_SCHED_LOCKED If the scheduler is locked
* OS_ERR_TIMEOUT A message was not received within the specified timeout
* would lead to a suspension
* OS_ERR_TICK_DISABLED If kernel ticks are disabled and a timeout is specified
*
* Returns : A pointer to the message received or a NULL pointer upon error.
*
* Note(s) : 1) It is possible to receive NULL pointers when there are no errors.
*
* : 2) This API 'MUST NOT' be called from a timer callback function.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_Q_EN > 0u)
/**
* @brief 掛起任務以等待訊息佇列中的訊息
*
* 本函式用於掛起當前任務，以等待其訊息佇列中的訊息。如果訊息佇列中有可用訊息，則接收並返回該訊息；
* 否則，根據指定的選項掛起任務，直到訊息可用或達到指定的超時時間。
*
* @param timeout 超時時間，如果為0，則無限期等待
* @param opt 指定操作選項，可以是阻塞或非阻塞操作
* @param p_msg_size 指向接收訊息大小的指標
* @param p_ts 指向接收時間戳的指標
* @param p_err 指向錯誤程式碼的指標
* @return void* 返回接收到的訊息，如果沒有訊息則返回NULL
*/
void *OSTaskQPend(OS_TICK timeout,
OS_OPT opt,
OS_MSG_SIZE *p_msg_size,
CPU_TS *p_ts,
OS_ERR *p_err)
{
OS_MSG_Q *p_msg_q;
void *p_void;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保錯誤指標非空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return ((void *)0);
}
#endif
// 跟蹤任務訊息佇列掛起進入
OS_TRACE_TASK_MSG_Q_PEND_ENTER(&OSTCBCurPtr->MsgQ, timeout, opt, p_msg_size, p_ts);
// 如果定時器禁用且指定了非零超時，則返回錯誤
#if (OS_CFG_TICK_EN == 0u)
if (timeout != 0u)
{
*p_err = OS_ERR_TICK_DISABLED;
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_TICK_DISABLED);
return ((void *)0);
}
#endif
// 檢查是否從ISR呼叫：ISR中不能掛起任務
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* Can't Pend from an ISR */
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_PEND_ISR);
*p_err = OS_ERR_PEND_ISR;
return ((void *)0);
}
#endif
// 檢查核心是否正在執行
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_OS_NOT_RUNNING);
*p_err = OS_ERR_OS_NOT_RUNNING;
return ((void *)0);
}
#endif
// 引數有效性檢查：確保訊息大小指標非空，並驗證選項引數
#if (OS_CFG_ARG_CHK_EN > 0u) /* ---------------- VALIDATE ARGUMENTS ---------------- */
if (p_msg_size == (OS_MSG_SIZE *)0)
{ /* User must supply a valid destination for msg size */
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_PTR_INVALID);
*p_err = OS_ERR_PTR_INVALID;
return ((void *)0);
}
switch (opt)
{ /* User must supply a valid option */
case OS_OPT_PEND_BLOCKING:
case OS_OPT_PEND_NON_BLOCKING:
break;
default:
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_OPT_INVALID);
*p_err = OS_ERR_OPT_INVALID;
return ((void *)0);
}
#endif
// 初始化返回的時間戳
if (p_ts != (CPU_TS *)0)
{
*p_ts = 0u; /* Initialize the returned timestamp */
}
// 進入臨界區，檢查訊息佇列中是否有訊息
CPU_CRITICAL_ENTER();
p_msg_q = &OSTCBCurPtr->MsgQ; /* Any message waiting in the message queue? */
p_void = OS_MsgQGet(p_msg_q,
p_msg_size,
p_ts,
p_err);
if (*p_err == OS_ERR_NONE)
{
// 如果配置了任務分析和時間戳，則計算訊息佇列等待時間
#if (OS_CFG_TASK_PROFILE_EN > 0u)
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
OSTCBCurPtr->MsgQPendTime = OS_TS_GET() - *p_ts;
if (OSTCBCurPtr->MsgQPendTimeMax < OSTCBCurPtr->MsgQPendTime)
{
OSTCBCurPtr->MsgQPendTimeMax = OSTCBCurPtr->MsgQPendTime;
}
}
#endif
#endif
// 跟蹤任務訊息佇列掛起成功
OS_TRACE_TASK_MSG_Q_PEND(p_msg_q);
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_NONE);
return (p_void); /* Yes, Return oldest message received */
}
// 如果是非阻塞呼叫且沒有可用訊息，則返回錯誤
if ((opt & OS_OPT_PEND_NON_BLOCKING) != 0u)
{ /* Caller wants to block if not available? */
*p_err = OS_ERR_PEND_WOULD_BLOCK; /* No */
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_MSG_Q_PEND_FAILED(p_msg_q);
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_PEND_WOULD_BLOCK);
return ((void *)0);
}
else
{ /* Yes */
// 如果排程程式被鎖定，則不能掛起任務
if (OSSchedLockNestingCtr > 0u)
{ /* Can't block when the scheduler is locked */
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_MSG_Q_PEND_FAILED(p_msg_q);
OS_TRACE_TASK_MSG_Q_PEND_EXIT(OS_ERR_SCHED_LOCKED);
*p_err = OS_ERR_SCHED_LOCKED;
return ((void *)0);
}
}
// 將任務掛起到訊息佇列上，並呼叫排程程式尋找下一個就緒任務
OS_Pend((OS_PEND_OBJ *)0, /* Block task pending on Message */
OSTCBCurPtr,
OS_TASK_PEND_ON_TASK_Q,
timeout);
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_MSG_Q_PEND_BLOCK(p_msg_q);
OSSched(); /* Find the next highest priority task ready to run */
// 根據任務掛起狀態處理相應邏輯
CPU_CRITICAL_ENTER();
switch (OSTCBCurPtr->PendStatus)
{
case OS_STATUS_PEND_OK: /* Extract message from TCB (Put there by Post) */
p_void = OSTCBCurPtr->MsgPtr;
*p_msg_size = OSTCBCurPtr->MsgSize;
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = OSTCBCurPtr->TS;
#if (OS_CFG_TASK_PROFILE_EN > 0u)
OSTCBCurPtr->MsgQPendTime = OS_TS_GET() - OSTCBCurPtr->TS;
if (OSTCBCurPtr->MsgQPendTimeMax < OSTCBCurPtr->MsgQPendTime)
{
OSTCBCurPtr->MsgQPendTimeMax = OSTCBCurPtr->MsgQPendTime;
}
#endif
}
#endif
OS_TRACE_TASK_MSG_Q_PEND(p_msg_q);
*p_err = OS_ERR_NONE;
break;
case OS_STATUS_PEND_ABORT: /* Indicate that we aborted */
p_void = (void *)0;
*p_msg_size = 0u;
if (p_ts != (CPU_TS *)0)
{
*p_ts = 0u;
}
OS_TRACE_TASK_MSG_Q_PEND_FAILED(p_msg_q);
*p_err = OS_ERR_PEND_ABORT;
break;
case OS_STATUS_PEND_TIMEOUT: /* Indicate that we didn't get event within TO */
default:
p_void = (void *)0;
*p_msg_size = 0u;
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = OSTCBCurPtr->TS;
}
#endif
OS_TRACE_TASK_MSG_Q_PEND_FAILED(p_msg_q);
*p_err = OS_ERR_TIMEOUT;
break;
}
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_MSG_Q_PEND_EXIT(*p_err);
return (p_void); /* Return received message */
}
#endif
/*
************************************************************************************************************************
* ABORT WAITING FOR A MESSAGE
*
* Description: This function aborts & readies the task specified. This function should be used to fault-abort the wait
* for a message, rather than to normally post the message to the task via OSTaskQPost().
*
* Arguments : p_tcb is a pointer to the task to pend abort
*
* opt provides options for this function:
*
* OS_OPT_POST_NONE No option specified
* OS_OPT_POST_NO_SCHED Indicates that the scheduler will not be called.
*
* p_err is a pointer to a variable that will contain an error code returned by this function.
*
* OS_ERR_NONE If the task was readied and informed of the aborted wait
* OS_ERR_OPT_INVALID If you specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_PEND_ABORT_ISR If you called this function from an ISR
* OS_ERR_PEND_ABORT_NONE If task was not pending on a message and thus there is nothing to
* abort
* OS_ERR_PEND_ABORT_SELF If you passed a NULL pointer for 'p_tcb'
*
* Returns : == OS_FALSE if task was not waiting for a message, or upon error.
* == OS_TRUE if task was waiting for a message and was readied and informed.
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_Q_EN > 0u) && (OS_CFG_TASK_Q_PEND_ABORT_EN > 0u)
/**
* @brief 中止一個任務的佇列等待操作
*
* 本函式用於中止指定任務在佇列上的等待操作。如果任務當前正在等待佇列中的訊息，
* 則中止其等待，並可選擇是否重新排程。
*
* @param p_tcb 指向任務控制塊的指標，標識需要中止等待的任務
* @param opt 控制選項，決定是否在中止後重新排程
* @param p_err 指向錯誤程式碼的指標，用於返回錯誤資訊
* @return CPU_BOOLEAN 返回一個布林值，指示操作是否成功
*/
CPU_BOOLEAN OSTaskQPendAbort(OS_TCB *p_tcb,
OS_OPT opt,
OS_ERR *p_err)
{
CPU_TS ts;
CPU_SR_ALLOC();
// 安全性檢查：確保p_err引數不為空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (OS_FALSE);
}
#endif
// 檢查是否從ISR中呼叫：不允許從ISR中呼叫本函式
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* See if called from ISR ... */
*p_err = OS_ERR_PEND_ABORT_ISR; /* ... can't Pend Abort from an ISR */
return (OS_FALSE);
}
#endif
// 檢查核心是否正在執行：確保核心處於執行狀態
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
*p_err = OS_ERR_OS_NOT_RUNNING;
return (OS_FALSE);
}
#endif
// 引數驗證：確保opt引數為有效選項
#if (OS_CFG_ARG_CHK_EN > 0u) /* ---------------- VALIDATE ARGUMENTS ---------------- */
switch (opt)
{ /* User must supply a valid option */
case OS_OPT_POST_NONE:
case OS_OPT_POST_NO_SCHED:
break;
default:
*p_err = OS_ERR_OPT_INVALID;
return (OS_FALSE);
}
#endif
CPU_CRITICAL_ENTER();
#if (OS_CFG_ARG_CHK_EN > 0u)
if ((p_tcb == (OS_TCB *)0) || /* Pend abort self? */
(p_tcb == OSTCBCurPtr))
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_PEND_ABORT_SELF; /* ... doesn't make sense */
return (OS_FALSE);
}
#endif
// 檢查任務是否正在等待佇列訊息
if (p_tcb->PendOn != OS_TASK_PEND_ON_TASK_Q)
{ /* Is task waiting for a message? */
CPU_CRITICAL_EXIT(); /* No */
*p_err = OS_ERR_PEND_ABORT_NONE;
return (OS_FALSE);
}
// 獲取當前時間戳（如果配置了時間戳功能）
#if (OS_CFG_TS_EN > 0u)
ts = OS_TS_GET(); /* Get timestamp of when the abort occurred */
#else
ts = 0u;
#endif
// 中止任務的等待操作
OS_PendAbort(p_tcb, /* Abort the pend */
ts,
OS_STATUS_PEND_ABORT);
CPU_CRITICAL_EXIT();
// 根據選項決定是否重新排程
if ((opt & OS_OPT_POST_NO_SCHED) == 0u)
{
OSSched(); /* Run the scheduler */
}
// 返回成功錯誤碼
*p_err = OS_ERR_NONE;
return (OS_TRUE);
}
#endif
/*
************************************************************************************************************************
* POST MESSAGE TO A TASK
*
* Description: This function sends a message to a task.
*
* Arguments : p_tcb is a pointer to the TCB of the task receiving a message. If you specify a NULL pointer then
* the message will be posted to the task's queue of the calling task. In other words, you'd be
* posting a message to yourself.
*
* p_void is a pointer to the message to send.
*
* msg_size is the size of the message sent (in bytes)
*
* opt specifies whether the post will be FIFO or LIFO:
*
* OS_OPT_POST_FIFO Post at the end of the queue
* OS_OPT_POST_LIFO Post at the front of the queue
*
* OS_OPT_POST_NO_SCHED Do not run the scheduler after the post
*
* Note(s): 1) OS_OPT_POST_NO_SCHED can be added with one of the other options.
*
*
* p_err is a pointer to a variable that will hold the error code associated
* with the outcome of this call. Errors can be:
*
* OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_MSG_POOL_EMPTY If there are no more OS_MSGs available from the pool
* OS_ERR_OPT_INVALID If you specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_Q_MAX If the queue is full
* OS_ERR_STATE_INVALID If the task is in an invalid state. This should never happen
* and if it does, would be considered a system failure
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_Q_EN > 0u)
/**
* @brief 向任務的訊息佇列傳送訊息
*
* 該函式用於將訊息傳送到指定任務的訊息佇列中。根據任務的狀態和提供的選項，
* 訊息可能會直接傳遞給任務或者排隊在訊息佇列中。此函式是作業系統的一部分，
* 提供了任務間通訊的能力。
*
* @param p_tcb 指向任務控制塊的指標，標識訊息接收的任務
* @param p_void 指向要傳送的訊息的指標
* @param msg_size 訊息的大小，以位元組為單位
* @param opt 傳送訊息的選項，控制訊息的傳送方式（如FIFO或LIFO）和是否重新排程
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行的結果
*/
void OSTaskQPost(OS_TCB *p_tcb,
void *p_void,
OS_MSG_SIZE msg_size,
OS_OPT opt,
OS_ERR *p_err)
{
CPU_TS ts;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保錯誤指標非空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 跟蹤：記錄任務訊息佇列傳送開始
OS_TRACE_TASK_MSG_Q_POST_ENTER(&p_tcb->MsgQ, p_void, msg_size, opt);
// 檢查核心是否正在執行
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
OS_TRACE_TASK_MSG_Q_POST_EXIT(OS_ERR_OS_NOT_RUNNING);
*p_err = OS_ERR_OS_NOT_RUNNING;
return;
}
#endif
// 引數有效性檢查
#if (OS_CFG_ARG_CHK_EN > 0u) /* ---------------- VALIDATE ARGUMENTS ---------------- */
switch (opt)
{ /* User must supply a valid option */
case OS_OPT_POST_FIFO:
case OS_OPT_POST_LIFO:
case OS_OPT_POST_FIFO | OS_OPT_POST_NO_SCHED:
case OS_OPT_POST_LIFO | OS_OPT_POST_NO_SCHED:
break;
default:
OS_TRACE_TASK_MSG_Q_POST_FAILED(&p_tcb->MsgQ);
OS_TRACE_TASK_MSG_Q_POST_EXIT(OS_ERR_OPT_INVALID);
*p_err = OS_ERR_OPT_INVALID;
return;
}
#endif
// 獲取時間戳（如果配置了時間戳功能）
#if (OS_CFG_TS_EN > 0u)
ts = OS_TS_GET(); /* Get timestamp */
#else
ts = 0u;
#endif
// 跟蹤：記錄任務訊息佇列傳送過程
OS_TRACE_TASK_MSG_Q_POST(&p_tcb->MsgQ);
// 預設假設沒有錯誤
*p_err = OS_ERR_NONE; /* Assume we won't have any errors */
CPU_CRITICAL_ENTER();
// 如果任務控制塊指標為0，則將其指向當前任務
if (p_tcb == (OS_TCB *)0)
{ /* Post msg to 'self'? */
p_tcb = OSTCBCurPtr;
}
// 根據任務的狀態處理訊息傳送
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
case OS_TASK_STATE_DLY:
case OS_TASK_STATE_SUSPENDED:
case OS_TASK_STATE_DLY_SUSPENDED:
// 將訊息放入任務的訊息佇列中
OS_MsgQPut(&p_tcb->MsgQ, /* Deposit the message in the queue */
p_void,
msg_size,
opt,
ts,
p_err);
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND:
case OS_TASK_STATE_PEND_TIMEOUT:
case OS_TASK_STATE_PEND_SUSPENDED:
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
// 檢查任務是否正在等待訊息佇列的訊息
if (p_tcb->PendOn == OS_TASK_PEND_ON_TASK_Q)
{ /* Is task waiting for a message to be sent to it? */
OS_Post((OS_PEND_OBJ *)0,
p_tcb,
p_void,
msg_size,
ts);
CPU_CRITICAL_EXIT();
// 如果沒有設定禁止排程選項，則執行排程器
if ((opt & OS_OPT_POST_NO_SCHED) == 0u)
{
OSSched(); /* Run the scheduler */
}
}
else
{
// 如果任務在等待其他資源，將訊息放入任務的訊息佇列中
OS_MsgQPut(&p_tcb->MsgQ, /* No, Task is pending on something else ... */
p_void, /* ... Deposit the message in the task's queue */
msg_size,
opt,
ts,
p_err);
CPU_CRITICAL_EXIT();
}
break;
default:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_STATE_INVALID;
break;
}
// 跟蹤：記錄任務訊息佇列傳送結束
OS_TRACE_TASK_MSG_Q_POST_EXIT(*p_err);
}
#endif
/*
************************************************************************************************************************
* GET THE CURRENT VALUE OF A TASK REGISTER
*
* Description: This function is called to obtain the current value of a task register. Task registers are application
* specific and can be used to store task specific values such as 'error numbers' (i.e. errno), statistics,
* etc.
*
* Arguments : p_tcb is a pointer to the OS_TCB of the task you want to read the register from. If 'p_tcb' is a
* NULL pointer then you will get the register of the current task.
*
* id is the 'id' of the desired task variable. Note that the 'id' must be less than
* OS_CFG_TASK_REG_TBL_SIZE
*
* p_err is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE If the call was successful
* OS_ERR_REG_ID_INVALID If the 'id' is not between 0 and OS_CFG_TASK_REG_TBL_SIZE-1
*
* Returns : The current value of the task's register or 0 if an error is detected.
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
/**
* @brief 獲取任務的暫存器值
*
* 該函式用於獲取指定任務的某個暫存器值。它透過任務控制塊(p_tcb)、暫存器ID(id)來定位暫存器，
* 並將暫存器的值返回。函式還透過p_err引數返回錯誤程式碼。
*
* @param p_tcb 指向任務控制塊的指標，用於標識任務。如果為NULL，將使用當前任務的TCB。
* @param id 暫存器ID，用於指定需要獲取的暫存器。
* @param p_err 指向錯誤程式碼的指標，用於返回錯誤程式碼。
* @return 返回指定暫存器的值。
*/
OS_REG OSTaskRegGet(OS_TCB *p_tcb,
OS_REG_ID id,
OS_ERR *p_err)
{
OS_REG value;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保錯誤程式碼指標不為NULL
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
// 引數有效性檢查：確保暫存器ID在有效範圍內
#if (OS_CFG_ARG_CHK_EN > 0u)
if (id >= OS_CFG_TASK_REG_TBL_SIZE)
{
*p_err = OS_ERR_REG_ID_INVALID;
return (0u);
}
#endif
// 進入臨界區，保護任務控制塊和暫存器表的訪問
CPU_CRITICAL_ENTER();
if (p_tcb == (OS_TCB *)0)
{
p_tcb = OSTCBCurPtr;
}
value = p_tcb->RegTbl[id];
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_NONE;
return (value);
}
#endif
/*
************************************************************************************************************************
* ALLOCATE THE NEXT AVAILABLE TASK REGISTER ID
*
* Description: This function is called to obtain a task register ID. This function thus allows task registers IDs to be
* allocated dynamically instead of statically.
*
* Arguments : p_err is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE If the call was successful
* OS_ERR_NO_MORE_ID_AVAIL If you are attempting to assign more task register IDs than you
* have available through OS_CFG_TASK_REG_TBL_SIZE
*
* Returns : The next available task register 'id' or OS_CFG_TASK_REG_TBL_SIZE if an error is detected.
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
// 獲取下一個可用的任務暫存器ID
OS_REG_ID OSTaskRegGetID(OS_ERR *p_err)
{
OS_REG_ID id;
CPU_SR_ALLOC();
// 在安全關鍵模式下，檢查錯誤引數是否為空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_REG_ID)OS_CFG_TASK_REG_TBL_SIZE);
}
#endif
CPU_CRITICAL_ENTER();
// 檢查是否超過了可用ID的數量
if (OSTaskRegNextAvailID >= OS_CFG_TASK_REG_TBL_SIZE)
{
*p_err = OS_ERR_NO_MORE_ID_AVAIL; // 如果是，設定錯誤程式碼並返回
CPU_CRITICAL_EXIT();
return (OS_CFG_TASK_REG_TBL_SIZE);
}
id = OSTaskRegNextAvailID; // 分配下一個可用的ID
OSTaskRegNextAvailID++; // 為下一次請求增加可用ID
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_NONE; // 設定無錯誤程式碼
return (id);
}
#endif
/*
************************************************************************************************************************
* SET THE CURRENT VALUE OF A TASK REGISTER
*
* Description: This function is called to change the current value of a task register. Task registers are application
* specific and can be used to store task specific values such as 'error numbers' (i.e. errno), statistics,
* etc.
*
* Arguments : p_tcb is a pointer to the OS_TCB of the task you want to set the register for. If 'p_tcb' is a NULL
* pointer then you will change the register of the current task.
*
* id is the 'id' of the desired task register. Note that the 'id' must be less than
* OS_CFG_TASK_REG_TBL_SIZE
*
* value is the desired value for the task register.
*
* p_err is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE If the call was successful
* OS_ERR_REG_ID_INVALID If the 'id' is not between 0 and OS_CFG_TASK_REG_TBL_SIZE-1
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
/**
* @brief 設定任務的登錄檔項值
*
* 本函式用於在任務控制塊(TCB)中設定指定登錄檔項的值。這在需要記錄或更改任務特定資訊時非常有用。
*
* @param p_tcb 指向任務控制塊(OS_TCB)的指標。如果為NULL，將使用當前任務的TCB。
* @param id 登錄檔項的ID，標識特定的登錄檔項。
* @param value 要設定的登錄檔項的值。
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行結果的錯誤資訊。
*/
void OSTaskRegSet(OS_TCB *p_tcb,
OS_REG_ID id,
OS_REG value,
OS_ERR *p_err)
{
// 分配CPU狀態暫存器
CPU_SR_ALLOC();
// 在安全關鍵模式下，檢查錯誤引數是否為空，如果為空則觸發安全關鍵異常並返回
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 在配置了引數檢查的情況下，檢查登錄檔項ID是否有效，如果無效則設定錯誤程式碼並返回
#if (OS_CFG_ARG_CHK_EN > 0u)
if (id >= OS_CFG_TASK_REG_TBL_SIZE)
{
*p_err = OS_ERR_REG_ID_INVALID;
return;
}
#endif
// 進入臨界區，以防止在設定登錄檔項值時被中斷
CPU_CRITICAL_ENTER();
// 如果傳入的TCB指標為空，則使用當前任務的TCB
if (p_tcb == (OS_TCB *)0)
{
p_tcb = OSTCBCurPtr;
}
// 設定指定登錄檔項的值
p_tcb->RegTbl[id] = value;
// 退出臨界區
CPU_CRITICAL_EXIT();
// 設定錯誤程式碼為無錯誤
*p_err = OS_ERR_NONE;
}
#endif
/*
************************************************************************************************************************
* RESUME A SUSPENDED TASK
*
* Description: This function is called to resume a previously suspended task. This is the only call that will remove an
* explicit task suspension.
*
* Arguments : p_tcb Is a pointer to the task's OS_TCB to resume
*
* p_err Is a pointer to a variable that will contain an error code returned by this function
*
* OS_ERR_NONE If the requested task is resumed
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_STATE_INVALID If the task is in an invalid state
* OS_ERR_TASK_NOT_SUSPENDED If the task to resume has not been suspended
* OS_ERR_TASK_RESUME_ISR If you called this function from an ISR
* OS_ERR_TASK_RESUME_SELF You cannot resume 'self'
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_SUSPEND_EN > 0u)
/**
* @brief 恢復一個被掛起的任務
*
* 此函式用於恢復之前被掛起的任務。它會檢查當前任務的狀態，並根據狀態決定是否將任務重新插入到就緒列表中。
*
* @param p_tcb 指向任務控制塊的指標，標識要恢復的任務
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行的結果
*/
void OSTaskResume(OS_TCB *p_tcb,
OS_ERR *p_err)
{
CPU_SR_ALLOC(); // 定義CPU狀態暫存器變數
OS_TRACE_TASK_RESUME_ENTER(p_tcb); // 跟蹤任務恢復入口
// 安全關鍵應用檢查
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 檢查是否在中斷中呼叫
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* Not allowed to call from an ISR */
*p_err = OS_ERR_TASK_RESUME_ISR;
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_TASK_RESUME_ISR);
return;
}
#endif
// 檢查作業系統是否正在執行
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
*p_err = OS_ERR_OS_NOT_RUNNING;
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_OS_NOT_RUNNING);
return;
}
#endif
// 引數檢查
#if (OS_CFG_ARG_CHK_EN > 0u)
CPU_CRITICAL_ENTER();
if ((p_tcb == (OS_TCB *)0) || /* We cannot resume 'self' */
(p_tcb == OSTCBCurPtr))
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_TASK_RESUME_SELF;
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_TASK_RESUME_SELF);
return;
}
CPU_CRITICAL_EXIT();
#endif
CPU_CRITICAL_ENTER();
*p_err = OS_ERR_NONE;
// 根據任務狀態進行相應操作
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
case OS_TASK_STATE_DLY:
case OS_TASK_STATE_PEND:
case OS_TASK_STATE_PEND_TIMEOUT:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_TASK_NOT_SUSPENDED;
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_TASK_NOT_SUSPENDED);
break;
case OS_TASK_STATE_SUSPENDED:
p_tcb->SuspendCtr--;
if (p_tcb->SuspendCtr == 0u)
{
p_tcb->TaskState = OS_TASK_STATE_RDY;
OS_RdyListInsert(p_tcb); /* Insert the task in the ready list */
OS_TRACE_TASK_RESUME(p_tcb);
}
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_DLY_SUSPENDED:
p_tcb->SuspendCtr--;
if (p_tcb->SuspendCtr == 0u)
{
p_tcb->TaskState = OS_TASK_STATE_DLY;
}
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND_SUSPENDED:
p_tcb->SuspendCtr--;
if (p_tcb->SuspendCtr == 0u)
{
p_tcb->TaskState = OS_TASK_STATE_PEND;
}
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
p_tcb->SuspendCtr--;
if (p_tcb->SuspendCtr == 0u)
{
p_tcb->TaskState = OS_TASK_STATE_PEND_TIMEOUT;
}
CPU_CRITICAL_EXIT();
break;
default:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_STATE_INVALID;
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_STATE_INVALID);
break;
}
// 如果任務不在掛起狀態，則不進行排程
if (*p_err != OS_ERR_NONE)
{
return;
}
OSSched(); // 排程任務
OS_TRACE_TASK_RESUME_EXIT(OS_ERR_NONE); // 跟蹤任務恢復出口
}
#endif
/*
************************************************************************************************************************
* WAIT FOR A TASK SEMAPHORE
*
* Description: This function is called to block the current task until a signal is sent by another task or ISR.
*
* Arguments : timeout is the amount of time you are will to wait for the signal
*
* opt determines whether the user wants to block if a semaphore post was not received:
*
* OS_OPT_PEND_BLOCKING
* OS_OPT_PEND_NON_BLOCKING
*
* p_ts is a pointer to a variable that will receive the timestamp of when the semaphore was posted
* or pend aborted. If you pass a NULL pointer (i.e. (CPU_TS *)0) then you will not get the
* timestamp. In other words, passing a NULL pointer is valid and indicates that you don't
* need the timestamp.
*
* p_err is a pointer to an error code that will be set by this function
*
* OS_ERR_NONE The call was successful and your task received a message
* OS_ERR_OPT_INVALID You specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_PEND_ABORT If the pend was aborted
* OS_ERR_PEND_ISR If you called this function from an ISR
* OS_ERR_PEND_WOULD_BLOCK If you specified non-blocking but no signal was received
* OS_ERR_SCHED_LOCKED If the scheduler is locked
* OS_ERR_STATUS_INVALID If the pend status is invalid
* OS_ERR_TIMEOUT A message was not received within the specified timeout
*
* Returns : The current count of signals the task received, 0 if none.
*
* Note(s) : This API 'MUST NOT' be called from a timer callback function.
************************************************************************************************************************
*/
// 函式OSTaskSemPend用於當前任務等待訊號量。
// 引數timeout指定等待的超時時間，opt指定等待選項，p_ts用於接收時間戳，p_err用於接收錯誤程式碼。
// 返回值為當前訊號量計數器的值。
OS_SEM_CTR OSTaskSemPend(OS_TICK timeout,
OS_OPT opt,
CPU_TS *p_ts,
OS_ERR *p_err)
{
OS_SEM_CTR ctr;
CPU_SR_ALLOC();
// 當時間戳功能禁用時，防止編譯器對未使用的p_ts引數發出警告。
#if (OS_CFG_TS_EN == 0u)
(void)p_ts;
#endif
// 在安全關鍵系統中，如果p_err引數為空，則呼叫安全關鍵異常處理函式並返回0。
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
// 進入任務訊號量等待的跟蹤。
OS_TRACE_TASK_SEM_PEND_ENTER(OSTCBCurPtr, timeout, opt, p_ts);
// 當滴答功能禁用時，如果timeout不為0，則返回滴答禁用錯誤。
#if (OS_CFG_TICK_EN == 0u)
if (timeout != 0u)
{
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_TICK_DISABLED);
*p_err = OS_ERR_TICK_DISABLED;
return (0u);
}
#endif
// 檢查是否從ISR中呼叫，如果在中斷中呼叫則返回錯誤。
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_PEND_ISR);
*p_err = OS_ERR_PEND_ISR;
return (0u);
}
#endif
// 檢查核心是否正在執行，如果沒有執行則返回錯誤。
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_OS_NOT_RUNNING);
*p_err = OS_ERR_OS_NOT_RUNNING;
return (0u);
}
#endif
// 檢查opt引數的有效性，如果無效則返回錯誤。
#if (OS_CFG_ARG_CHK_EN > 0u)
switch (opt)
{
case OS_OPT_PEND_BLOCKING:
case OS_OPT_PEND_NON_BLOCKING:
break;
default:
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_OPT_INVALID);
*p_err = OS_ERR_OPT_INVALID;
return (0u);
}
#endif
// 進入臨界區，檢查當前任務的訊號量計數器。
CPU_CRITICAL_ENTER();
if (OSTCBCurPtr->SemCtr > 0u)
{
OSTCBCurPtr->SemCtr--;
ctr = OSTCBCurPtr->SemCtr;
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = OSTCBCurPtr->TS;
}
#if (OS_CFG_TASK_PROFILE_EN > 0u)
#if (OS_CFG_TS_EN > 0u)
OSTCBCurPtr->SemPendTime = OS_TS_GET() - OSTCBCurPtr->TS;
if (OSTCBCurPtr->SemPendTimeMax < OSTCBCurPtr->SemPendTime)
{
OSTCBCurPtr->SemPendTimeMax = OSTCBCurPtr->SemPendTime;
}
#endif
#endif
#endif
OS_TRACE_TASK_SEM_PEND(OSTCBCurPtr);
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_NONE);
*p_err = OS_ERR_NONE;
return (ctr);
}
// 如果設定了非阻塞選項但訊號量計數器為0，則返回錯誤。
if ((opt & OS_OPT_PEND_NON_BLOCKING) != 0u)
{
CPU_CRITICAL_EXIT();
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = 0u;
}
#endif
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_PEND_WOULD_BLOCK);
*p_err = OS_ERR_PEND_WOULD_BLOCK;
return (0u);
}
else
{
if (OSSchedLockNestingCtr > 0u)
{
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = 0u;
}
#endif
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
OS_TRACE_TASK_SEM_PEND_EXIT(OS_ERR_SCHED_LOCKED);
*p_err = OS_ERR_SCHED_LOCKED;
return (0u);
}
}
// 將當前任務掛起並排程其他任務。
OS_Pend((OS_PEND_OBJ *)0, /* Block task pending on Signal */
OSTCBCurPtr,
OS_TASK_PEND_ON_TASK_SEM,
timeout);
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_SEM_PEND_BLOCK(OSTCBCurPtr);
OSSched(); /* Find next highest priority task ready to run */
// 檢查掛起結果並更新錯誤程式碼和時間戳。
CPU_CRITICAL_ENTER();
switch (OSTCBCurPtr->PendStatus)
{
case OS_STATUS_PEND_OK:
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = OSTCBCurPtr->TS;
#if (OS_CFG_TASK_PROFILE_EN > 0u)
#if (OS_CFG_TS_EN > 0u)
OSTCBCurPtr->SemPendTime = OS_TS_GET() - OSTCBCurPtr->TS;
if (OSTCBCurPtr->SemPendTimeMax < OSTCBCurPtr->SemPendTime)
{
OSTCBCurPtr->SemPendTimeMax = OSTCBCurPtr->SemPendTime;
}
#endif
#endif
}
#endif
OS_TRACE_TASK_SEM_PEND(OSTCBCurPtr);
*p_err = OS_ERR_NONE;
break;
case OS_STATUS_PEND_ABORT:
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = OSTCBCurPtr->TS;
}
#endif
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
*p_err = OS_ERR_PEND_ABORT;
break;
case OS_STATUS_PEND_TIMEOUT:
#if (OS_CFG_TS_EN > 0u)
if (p_ts != (CPU_TS *)0)
{
*p_ts = 0u;
}
#endif
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
*p_err = OS_ERR_TIMEOUT;
break;
default:
OS_TRACE_TASK_SEM_PEND_FAILED(OSTCBCurPtr);
*p_err = OS_ERR_STATUS_INVALID;
break;
}
ctr = OSTCBCurPtr->SemCtr;
CPU_CRITICAL_EXIT();
OS_TRACE_TASK_SEM_PEND_EXIT(*p_err);
return (ctr);
}
/*
************************************************************************************************************************
* ABORT WAITING FOR A SIGNAL
*
* Description: This function aborts & readies the task specified. This function should be used to fault-abort the wait
* for a signal, rather than to normally post the signal to the task via OSTaskSemPost().
*
* Arguments : p_tcb is a pointer to the task to pend abort
*
* opt provides options for this function:
*
* OS_OPT_POST_NONE No option selected
* OS_OPT_POST_NO_SCHED Indicates that the scheduler will not be called.
*
* p_err is a pointer to a variable that will contain an error code returned by this function.
*
* OS_ERR_NONE If the task was readied and informed of the aborted wait
* OS_ERR_OPT_INVALID You specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_PEND_ABORT_ISR If you tried calling this function from an ISR
* OS_ERR_PEND_ABORT_NONE If the task was not waiting for a signal
* OS_ERR_PEND_ABORT_SELF If you attempted to pend abort the calling task. This is not
* possible since the calling task cannot be pending because it's
* running
*
* Returns : == OS_FALSE if task was not waiting for a message, or upon error.
* == OS_TRUE if task was waiting for a message and was readied and informed.
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_TASK_SEM_PEND_ABORT_EN > 0u)
/**
* @brief 中止一個任務的訊號量等待操作
*
* 本函式用於中止指定任務在訊號量上的等待操作。如果目標任務當前正在等待訊號量，
* 則將其從等待狀態中解脫出來。該函式還會進行一系列的錯誤檢查，以確保函式呼叫的合法性。
*
* @param p_tcb 指向任務控制塊的指標，標識需要中止等待操作的任務
* @param opt 控制選項，決定是否在中止等待後重新排程
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行的錯誤狀態
* @return CPU_BOOLEAN 返回一個布林值，指示函式是否成功執行
*/
CPU_BOOLEAN OSTaskSemPendAbort(OS_TCB *p_tcb,
OS_OPT opt,
OS_ERR *p_err)
{
CPU_TS ts;
CPU_SR_ALLOC();
// 安全性檢查：確保p_err引數不為空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (OS_FALSE);
}
#endif
// 檢查是否從ISR中呼叫：不允許在中斷服務例程中執行等待中止操作
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* See if called from ISR ... */
*p_err = OS_ERR_PEND_ABORT_ISR; /* ... can't Pend Abort from an ISR */
return (OS_FALSE);
}
#endif
// 檢查核心是否正在執行：確保在核心執行狀態下執行函式
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
*p_err = OS_ERR_OS_NOT_RUNNING;
return (OS_FALSE);
}
#endif
// 引數有效性檢查：確保opt引數為合法值
#if (OS_CFG_ARG_CHK_EN > 0u)
switch (opt)
{ /* Validate 'opt' */
case OS_OPT_POST_NONE:
case OS_OPT_POST_NO_SCHED:
break;
default:
*p_err = OS_ERR_OPT_INVALID;
return (OS_FALSE);
}
#endif
CPU_CRITICAL_ENTER();
// 自我檢查以避免無效操作：不允許任務中止自己的訊號量等待
if ((p_tcb == (OS_TCB *)0) || /* Pend abort self? */
(p_tcb == OSTCBCurPtr))
{
CPU_CRITICAL_EXIT(); /* ... doesn't make sense! */
*p_err = OS_ERR_PEND_ABORT_SELF;
return (OS_FALSE);
}
// 檢查任務是否正在等待訊號量
if (p_tcb->PendOn != OS_TASK_PEND_ON_TASK_SEM)
{ /* Is task waiting for a signal? */
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_PEND_ABORT_NONE;
return (OS_FALSE);
}
CPU_CRITICAL_EXIT();
CPU_CRITICAL_ENTER();
// 獲取當前時間戳（如果配置支援）
#if (OS_CFG_TS_EN > 0u)
ts = OS_TS_GET();
#else
ts = 0u;
#endif
// 執行等待中止操作
OS_PendAbort(p_tcb, /* Abort the pend */
ts,
OS_STATUS_PEND_ABORT);
CPU_CRITICAL_EXIT();
// 根據opt引數決定是否重新排程
if ((opt & OS_OPT_POST_NO_SCHED) == 0u)
{
OSSched(); /* Run the scheduler */
}
// 設定錯誤程式碼為無錯誤並返回成功
*p_err = OS_ERR_NONE;
return (OS_TRUE);
}
#endif
/*
************************************************************************************************************************
* SIGNAL A TASK
*
* Description: This function is called to signal a task waiting for a signal.
*
* Arguments : p_tcb is the pointer to the TCB of the task to signal. A NULL pointer indicates that you are sending
* a signal to yourself.
*
* opt determines the type of POST performed:
*
* OS_OPT_POST_NONE No option
* OS_OPT_POST_NO_SCHED Do not call the scheduler
*
* p_err is a pointer to an error code returned by this function:
*
* OS_ERR_NONE If the requested task is signaled
* OS_ERR_OPT_INVALID If you specified an invalid option
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_SEM_OVF If the post would cause the semaphore count to overflow
* OS_ERR_STATE_INVALID If the task is in an invalid state. This should never happen
* and if it does, would be considered a system failure
*
* Returns : The current value of the task's signal counter or 0 if called from an ISR
*
* Note(s) : none
************************************************************************************************************************
*/
// 函式OSTaskSemPost用於向一個任務傳送訊號，增加任務的訊號計數器
// 如果任務正在等待訊號，則將其就緒
// 引數p_tcb指向任務的控制塊
// 引數opt控制是否在傳送訊號後進行排程
// 引數p_err返回錯誤程式碼
// 返回值是任務的訊號計數器值
OS_SEM_CTR OSTaskSemPost(OS_TCB *p_tcb,
OS_OPT opt,
OS_ERR *p_err)
{
OS_SEM_CTR ctr;
CPU_TS ts;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查，確保p_err不為空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
// 追蹤任務訊號傳送開始
OS_TRACE_TASK_SEM_POST_ENTER(p_tcb, opt);
// 檢查核心是否正在執行
#if (OS_CFG_INVALID_OS_CALLS_CHK_EN > 0u)
if (OSRunning != OS_STATE_OS_RUNNING)
{ /* Is the kernel running? */
OS_TRACE_TASK_SEM_POST_EXIT(OS_ERR_OS_NOT_RUNNING);
*p_err = OS_ERR_OS_NOT_RUNNING;
return (0u);
}
#endif
// 引數檢查，確保opt值有效
#if (OS_CFG_ARG_CHK_EN > 0u)
switch (opt)
{ /* Validate 'opt' */
case OS_OPT_POST_NONE:
case OS_OPT_POST_NO_SCHED:
break;
default:
OS_TRACE_TASK_SEM_POST_FAILED(p_tcb);
OS_TRACE_TASK_SEM_POST_EXIT(OS_ERR_OPT_INVALID);
*p_err = OS_ERR_OPT_INVALID;
return (0u);
}
#endif
// 獲取時間戳
#if (OS_CFG_TS_EN > 0u)
ts = OS_TS_GET(); /* Get timestamp */
#else
ts = 0u;
#endif
// 追蹤任務訊號傳送
OS_TRACE_TASK_SEM_POST(p_tcb);
// 進入臨界區
CPU_CRITICAL_ENTER();
if (p_tcb == (OS_TCB *)0)
{ /* Post signal to 'self'? */
p_tcb = OSTCBCurPtr;
}
#if (OS_CFG_TS_EN > 0u)
p_tcb->TS = ts;
#endif
*p_err = OS_ERR_NONE; /* Assume we won't have any errors */
// 根據任務狀態進行相應操作
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
case OS_TASK_STATE_DLY:
case OS_TASK_STATE_SUSPENDED:
case OS_TASK_STATE_DLY_SUSPENDED:
// 如果任務的訊號計數器溢位，則返回錯誤
if (p_tcb->SemCtr == (OS_SEM_CTR)-1)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_SEM_OVF;
OS_TRACE_SEM_POST_EXIT(*p_err);
return (0u);
}
p_tcb->SemCtr++; /* Task signaled is not pending on anything */
ctr = p_tcb->SemCtr;
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND:
case OS_TASK_STATE_PEND_TIMEOUT:
case OS_TASK_STATE_PEND_SUSPENDED:
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
// 如果任務正在等待訊號，則將其就緒
if (p_tcb->PendOn == OS_TASK_PEND_ON_TASK_SEM)
{ /* Is task signaled waiting for a signal? */
OS_Post((OS_PEND_OBJ *)0, /* Task is pending on signal */
p_tcb,
(void *)0,
0u,
ts);
ctr = p_tcb->SemCtr;
CPU_CRITICAL_EXIT();
if ((opt & OS_OPT_POST_NO_SCHED) == 0u)
{
OSSched(); /* Run the scheduler */
}
}
else
{
// 如果任務的訊號計數器溢位，則返回錯誤
if (p_tcb->SemCtr == (OS_SEM_CTR)-1)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_SEM_OVF;
OS_TRACE_SEM_POST_EXIT(*p_err);
return (0u);
}
p_tcb->SemCtr++; /* No, Task signaled is NOT pending on semaphore ... */
ctr = p_tcb->SemCtr; /* ... it must be waiting on something else */
CPU_CRITICAL_EXIT();
}
break;
default:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_STATE_INVALID;
ctr = 0u;
break;
}
// 追蹤任務訊號傳送結束
OS_TRACE_TASK_SEM_POST_EXIT(*p_err);
return (ctr);
}
/*
************************************************************************************************************************
* SET THE SIGNAL COUNTER OF A TASK
*
* Description: This function is called to clear the signal counter
*
* Arguments : p_tcb is the pointer to the TCB of the task to clear the counter. If you specify a NULL pointer
* then the signal counter of the current task will be cleared.
*
* cnt is the desired value of the semaphore counter
*
* p_err is a pointer to an error code returned by this function
*
* OS_ERR_NONE If the signal counter of the requested task is set
* OS_ERR_SET_ISR If the function was called from an ISR
* OS_ERR_TASK_WAITING One or more tasks were waiting on the semaphore
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
// 設定任務訊號量的函式
OS_SEM_CTR OSTaskSemSet(OS_TCB *p_tcb,
OS_SEM_CTR cnt,
OS_ERR *p_err)
{
OS_SEM_CTR ctr;
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保錯誤引數非空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
// 檢查是否在中斷中呼叫：不允許在中斷中呼叫該函式
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* Not allowed to call from an ISR */
*p_err = OS_ERR_SET_ISR;
return (0u);
}
#endif
// 進入臨界區：保護任務控制塊訪問的原子性
CPU_CRITICAL_ENTER();
// 如果傳入的任務控制塊指標為空，則使用當前任務的控制塊
if (p_tcb == (OS_TCB *)0)
{
p_tcb = OSTCBCurPtr;
}
// 檢查任務狀態：不允許在任務等待時設定訊號量
if (((p_tcb->TaskState & OS_TASK_STATE_PEND) != 0u) && /* Not allowed when a task is waiting. */
(p_tcb->PendOn == OS_TASK_PEND_ON_TASK_SEM))
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_TASK_WAITING;
return (0u);
}
// 讀取並儲存當前訊號量計數
ctr = p_tcb->SemCtr;
// 設定新的訊號量計數
p_tcb->SemCtr = (OS_SEM_CTR)cnt;
// 退出臨界區
CPU_CRITICAL_EXIT();
// 設定錯誤碼為無錯誤並返回舊的訊號量計數
*p_err = OS_ERR_NONE;
return (ctr);
}
/*
************************************************************************************************************************
* STACK CHECKING
*
* Description: This function is called to calculate the amount of free memory left on the specified task's stack.
*
* Arguments : p_tcb is a pointer to the TCB of the task to check. If you specify a NULL pointer then
* you are specifying that you want to check the stack of the current task.
*
* p_free is a pointer to a variable that will receive the number of free 'entries' on the task's stack.
*
* p_used is a pointer to a variable that will receive the number of used 'entries' on the task's stack.
*
* p_err is a pointer to a variable that will contain an error code.
*
* OS_ERR_NONE Upon success
* OS_ERR_PTR_INVALID If either 'p_free' or 'p_used' are NULL pointers
* OS_ERR_TASK_NOT_EXIST If the stack pointer of the task is a NULL pointer
* OS_ERR_TASK_OPT If you did NOT specified OS_OPT_TASK_STK_CHK when the task
* was created
* OS_ERR_TASK_STK_CHK_ISR You called this function from an ISR
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_STAT_TASK_STK_CHK_EN > 0u)
/**
* @brief 檢查任務棧的使用情況
*
* 該函式用於檢查指定任務的棧使用情況，計算棧中未使用的空間和已使用的空間大小
*
* @param p_tcb 指向任務控制塊的指標，用於標識要檢查的任務
* @param p_free 指向用於儲存未使用棧空間大小的變數的指標
* @param p_used 指向用於儲存已使用棧空間大小的變數的指標
* @param p_err 指向用於儲存錯誤程式碼的變數的指標
*/
void OSTaskStkChk(OS_TCB *p_tcb,
CPU_STK_SIZE *p_free,
CPU_STK_SIZE *p_used,
OS_ERR *p_err)
{
CPU_STK_SIZE free_stk;
CPU_STK_SIZE stk_size;
CPU_STK *p_stk;
CPU_SR_ALLOC();
// 安全性檢查：確保錯誤指標有效
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 檢查是否在中斷服務程式中呼叫
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* See if trying to check stack from ISR */
*p_err = OS_ERR_TASK_STK_CHK_ISR;
return;
}
#endif
// 引數有效性檢查
#if (OS_CFG_ARG_CHK_EN > 0u)
if (p_free == (CPU_STK_SIZE *)0)
{ /* User must specify valid destinations for the sizes */
*p_err = OS_ERR_PTR_INVALID;
return;
}
if (p_used == (CPU_STK_SIZE *)0)
{
*p_err = OS_ERR_PTR_INVALID;
return;
}
#endif
// 進入臨界區，保護任務控制塊
CPU_CRITICAL_ENTER();
if (p_tcb == (OS_TCB *)0)
{ /* Check the stack of the current task? */
p_tcb = OSTCBCurPtr; /* Yes */
}
// 檢查任務是否存在
if (p_tcb->StkPtr == (CPU_STK *)0)
{ /* Make sure task exist */
CPU_CRITICAL_EXIT();
*p_free = 0u;
*p_used = 0u;
*p_err = OS_ERR_TASK_NOT_EXIST;
return;
}
// 檢查是否啟用了棧檢查選項
if ((p_tcb->Opt & OS_OPT_TASK_STK_CHK) == 0u)
{ /* Make sure stack checking option is set */
CPU_CRITICAL_EXIT();
*p_free = 0u;
*p_used = 0u;
*p_err = OS_ERR_TASK_OPT;
return;
}
// 根據棧增長方向設定棧指標起始位置
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO)
p_stk = p_tcb->StkBasePtr; /* Start at the lowest memory and go up */
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u)
p_stk += OS_CFG_TASK_STK_REDZONE_DEPTH;
#endif
#else
p_stk = p_tcb->StkBasePtr + p_tcb->StkSize - 1u; /* Start at the highest memory and go down */
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u)
p_stk -= OS_CFG_TASK_STK_REDZONE_DEPTH;
#endif
#endif
stk_size = p_tcb->StkSize;
CPU_CRITICAL_EXIT();
free_stk = 0u;
// 計算棧中未使用的空間大小
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO)
while ((free_stk < stk_size) &&
(*p_stk == 0u))
{
p_stk++;
free_stk++;
}
#else
while ((free_stk < stk_size) &&
(*p_stk == 0u))
{
free_stk++;
p_stk--;
}
#endif
// 更新使用者傳入的指標所指向的值
*p_free = free_stk;
*p_used = (stk_size - free_stk); /* Compute number of entries used on the stack */
*p_err = OS_ERR_NONE;
}
#endif
/*
************************************************************************************************************************
* CHECK THE STACK REDZONE OF A TASK
*
* Description: Verify a task's stack redzone.
*
* Arguments : p_tcb is a pointer to the TCB of the task to check or null for the current task.
*
* Returns : If the stack is corrupted (OS_FALSE) or not (OS_TRUE).
*
* Note(s) : These functions are INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u)
CPU_BOOLEAN OSTaskStkRedzoneChk(OS_TCB *p_tcb)
{
CPU_BOOLEAN stk_status;
if (p_tcb == (OS_TCB *)0)
{
p_tcb = OSTCBCurPtr;
}
/* Check if SP is valid: */
/* StkBase <= SP < (StkBase + StkSize) */
if ((p_tcb->StkPtr < p_tcb->StkBasePtr) ||
(p_tcb->StkPtr >= (p_tcb->StkBasePtr + p_tcb->StkSize)))
{
return (OS_FALSE);
}
stk_status = OS_TaskStkRedzoneChk(p_tcb->StkBasePtr, p_tcb->StkSize);
return (stk_status);
}
#endif
/*
************************************************************************************************************************
* SUSPEND A TASK
*
* Description: This function is called to suspend a task. The task can be the calling task if 'p_tcb' is a NULL pointer
* or the pointer to the TCB of the calling task.
*
* Arguments : p_tcb is a pointer to the TCB to suspend.
* If p_tcb is a NULL pointer then, suspend the current task.
*
* p_err is a pointer to a variable that will receive an error code from this function.
*
* OS_ERR_NONE If the requested task is suspended
* OS_ERR_OS_NOT_RUNNING If uC/OS-III is not running yet
* OS_ERR_SCHED_LOCKED You can't suspend the current task is the scheduler is
* locked
* OS_ERR_STATE_INVALID If the task is in an invalid state
* OS_ERR_TASK_SUSPEND_CTR_OVF If the nesting counter overflowed.
* OS_ERR_TASK_SUSPEND_ISR If you called this function from an ISR
* OS_ERR_TASK_SUSPEND_IDLE If you attempted to suspend the idle task which is not
* allowed
* OS_ERR_TASK_SUSPEND_INT_HANDLER If you attempted to suspend the idle task which is not
* allowed
*
* Returns : none
*
* Note(s) : 1) You should use this function with great care. If you suspend a task that is waiting for an event
* (i.e. a message, a semaphore, a queue ...) you will prevent this task from running when the event
* arrives.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_SUSPEND_EN > 0u)
/**
* 暫停一個任務的執行
*
* @param p_tcb 指向任務控制塊的指標，標識要暫停的任務
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行結果
*/
void OSTaskSuspend(OS_TCB *p_tcb,
OS_ERR *p_err)
{
CPU_SR_ALLOC();
// 進入任務暫停跟蹤
OS_TRACE_TASK_SUSPEND_ENTER(p_tcb);
// 在安全關鍵應用中，檢查錯誤引數是否為空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 檢查是否在中斷服務程式中呼叫，不允許在ISR中呼叫此函式
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{
*p_err = OS_ERR_TASK_SUSPEND_ISR;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_TASK_SUSPEND_ISR);
return;
}
#endif
// 檢查是否嘗試暫停空閒任務，不允許暫停空閒任務
#if (OS_CFG_TASK_IDLE_EN > 0u)
if (p_tcb == &OSIdleTaskTCB)
{
*p_err = OS_ERR_TASK_SUSPEND_IDLE;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_TASK_SUSPEND_IDLE);
return;
}
#endif
CPU_CRITICAL_ENTER();
// 檢查任務控制塊是否為空，如果為空則嘗試暫停當前任務
if (p_tcb == (OS_TCB *)0)
{
if (OSRunning != OS_STATE_OS_RUNNING)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_OS_NOT_RUNNING;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_OS_NOT_RUNNING);
return;
}
p_tcb = OSTCBCurPtr;
}
// 如果嘗試暫停當前任務，檢查排程程式是否鎖定
if (p_tcb == OSTCBCurPtr)
{
if (OSSchedLockNestingCtr > 0u)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_SCHED_LOCKED;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_SCHED_LOCKED);
return;
}
}
*p_err = OS_ERR_NONE;
// 根據任務狀態更新任務狀態和暫停計數器
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
p_tcb->TaskState = OS_TASK_STATE_SUSPENDED;
p_tcb->SuspendCtr = 1u;
OS_RdyListRemove(p_tcb);
OS_TRACE_TASK_SUSPEND(p_tcb);
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_DLY:
p_tcb->TaskState = OS_TASK_STATE_DLY_SUSPENDED;
p_tcb->SuspendCtr = 1u;
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND:
p_tcb->TaskState = OS_TASK_STATE_PEND_SUSPENDED;
p_tcb->SuspendCtr = 1u;
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_PEND_TIMEOUT:
p_tcb->TaskState = OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED;
p_tcb->SuspendCtr = 1u;
CPU_CRITICAL_EXIT();
break;
case OS_TASK_STATE_SUSPENDED:
case OS_TASK_STATE_DLY_SUSPENDED:
case OS_TASK_STATE_PEND_SUSPENDED:
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
if (p_tcb->SuspendCtr == (OS_NESTING_CTR)-1)
{
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_TASK_SUSPEND_CTR_OVF;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_TASK_SUSPEND_CTR_OVF);
return;
}
p_tcb->SuspendCtr++;
CPU_CRITICAL_EXIT();
break;
default:
CPU_CRITICAL_EXIT();
*p_err = OS_ERR_STATE_INVALID;
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_STATE_INVALID);
return;
}
// 如果核心正在執行，則進行任務排程
if (OSRunning == OS_STATE_OS_RUNNING)
{
OSSched();
OS_TRACE_TASK_SUSPEND_EXIT(OS_ERR_NONE);
}
}
#endif
/*
************************************************************************************************************************
* CHANGE A TASK'S TIME SLICE
*
* Description: This function is called to change the value of the task's specific time slice.
*
* Arguments : p_tcb is the pointer to the TCB of the task to change. If you specify an NULL pointer, the current
* task is assumed.
*
* time_quanta is the number of ticks before the CPU is taken away when round-robin scheduling is enabled.
*
* p_err is a pointer to an error code returned by this function:
*
* OS_ERR_NONE Upon success
* OS_ERR_SET_ISR If you called this function from an ISR
*
* Returns : none
*
* Note(s) : none
************************************************************************************************************************
*/
#if (OS_CFG_SCHED_ROUND_ROBIN_EN > 0u)
/**
* @brief 設定任務的時間片
*
* 該函式用於設定任務的執行時間片。如果時間片設定為0，則使用預設的時間片。
* 在中斷上下文中呼叫該函式會導致錯誤。
*
* @param p_tcb 指向任務控制塊的指標
* @param time_quanta 時間片的長度，單位為滴答
* @param p_err 指向錯誤程式碼的指標
*/
void OSTaskTimeQuantaSet(OS_TCB *p_tcb,
OS_TICK time_quanta,
OS_ERR *p_err)
{
CPU_SR_ALLOC();
// 安全關鍵程式碼檢查：確保錯誤引數指標非空
#ifdef OS_SAFETY_CRITICAL
if (p_err == (OS_ERR *)0)
{
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
// 檢查是否在中斷上下文中呼叫：不允許在中斷中呼叫該函式
#if (OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u)
if (OSIntNestingCtr > 0u)
{ /* Can't call this function from an ISR */
*p_err = OS_ERR_SET_ISR;
return;
}
#endif
// 進入臨界區：保護任務控制塊和時間片變數
CPU_CRITICAL_ENTER();
// 如果傳入的任務控制塊指標為空，則使用當前任務的控制塊
if (p_tcb == (OS_TCB *)0)
{
p_tcb = OSTCBCurPtr;
}
// 如果時間片為0，則使用預設時間片，否則使用傳入的時間片
if (time_quanta == 0u)
{
p_tcb->TimeQuanta = OSSchedRoundRobinDfltTimeQuanta;
}
else
{
p_tcb->TimeQuanta = time_quanta;
}
// 如果新設定的時間片大於當前時間片計數器，則更新時間片計數器
if (p_tcb->TimeQuanta > p_tcb->TimeQuantaCtr)
{
p_tcb->TimeQuantaCtr = p_tcb->TimeQuanta;
}
// 退出臨界區
CPU_CRITICAL_EXIT();
// 設定錯誤程式碼為無錯誤
*p_err = OS_ERR_NONE;
}
#endif
/*
************************************************************************************************************************
* ADD/REMOVE TASK TO/FROM DEBUG LIST
*
* Description: These functions are called by uC/OS-III to add or remove an OS_TCB from the debug list.
*
* Arguments : p_tcb is a pointer to the OS_TCB to add/remove
*
* Returns : none
*
* Note(s) : These functions are INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
#if (OS_CFG_DBG_EN > 0u)
void OS_TaskDbgListAdd(OS_TCB *p_tcb)
{
p_tcb->DbgPrevPtr = (OS_TCB *)0;
if (OSTaskDbgListPtr == (OS_TCB *)0)
{
p_tcb->DbgNextPtr = (OS_TCB *)0;
}
else
{
p_tcb->DbgNextPtr = OSTaskDbgListPtr;
OSTaskDbgListPtr->DbgPrevPtr = p_tcb;
}
OSTaskDbgListPtr = p_tcb;
}
void OS_TaskDbgListRemove(OS_TCB *p_tcb)
{
OS_TCB *p_tcb_next;
OS_TCB *p_tcb_prev;
p_tcb_prev = p_tcb->DbgPrevPtr;
p_tcb_next = p_tcb->DbgNextPtr;
if (p_tcb_prev == (OS_TCB *)0)
{
OSTaskDbgListPtr = p_tcb_next;
if (p_tcb_next != (OS_TCB *)0)
{
p_tcb_next->DbgPrevPtr = (OS_TCB *)0;
}
p_tcb->DbgNextPtr = (OS_TCB *)0;
}
else if (p_tcb_next == (OS_TCB *)0)
{
p_tcb_prev->DbgNextPtr = (OS_TCB *)0;
p_tcb->DbgPrevPtr = (OS_TCB *)0;
}
else
{
p_tcb_prev->DbgNextPtr = p_tcb_next;
p_tcb_next->DbgPrevPtr = p_tcb_prev;
p_tcb->DbgNextPtr = (OS_TCB *)0;
p_tcb->DbgPrevPtr = (OS_TCB *)0;
}
}
#endif
/*
************************************************************************************************************************
* TASK MANAGER INITIALIZATION
*
* Description: This function is called by OSInit() to initialize the task management.
*
* Argument(s): p_err is a pointer to a variable that will contain an error code returned by this function.
*
* OS_ERR_NONE the call was successful
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
/**
* 初始化任務模組
*
* 該函式在系統初始化階段對任務相關的全域性變數進行設定
* 主要包括任務除錯連結串列指標、任務數量和任務上下文切換計數器的初始化
*
* @param p_err 指向錯誤程式碼的指標，用於返回函式執行結果
*/
void OS_TaskInit(OS_ERR *p_err)
{
// 在除錯配置下，初始化任務除錯連結串列指標為NULL
#if (OS_CFG_DBG_EN > 0u)
OSTaskDbgListPtr = (OS_TCB *)0;
#endif
// 清除任務數量，表示系統當前沒有建立任何任務
OSTaskQty = 0u; /* Clear the number of tasks */
// 在任務配置或除錯配置下，清除上下文切換計數器
#if ((OS_CFG_TASK_PROFILE_EN > 0u) || (OS_CFG_DBG_EN > 0u))
OSTaskCtxSwCtr = 0u; /* Clear the context switch counter */
#endif
// 設定錯誤程式碼為無錯誤，表示函式執行成功
*p_err = OS_ERR_NONE;
}
/*
************************************************************************************************************************
* INITIALIZE TCB FIELDS
*
* Description: This function is called to initialize a TCB to default values
*
* Arguments : p_tcb is a pointer to the TCB to initialize
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
// 初始化任務控制塊(TCB)
void OS_TaskInitTCB(OS_TCB *p_tcb)
{
// 如果任務暫存器表大小大於0，則初始化相關暫存器
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
OS_REG_ID reg_id;
#endif
// 如果定義了執行緒區域性儲存表大小且大於0，則初始化相關TLS
#if defined(OS_CFG_TLS_TBL_SIZE) && (OS_CFG_TLS_TBL_SIZE > 0u)
OS_TLS_ID id;
#endif
// 初始化棧指標和棧限制指標為NULL
p_tcb->StkPtr = (CPU_STK *)0;
p_tcb->StkLimitPtr = (CPU_STK *)0;
// 初始化擴充套件指標為NULL
p_tcb->ExtPtr = (void *)0;
// 初始化雙向連結串列的前後指標為NULL
p_tcb->NextPtr = (OS_TCB *)0;
p_tcb->PrevPtr = (OS_TCB *)0;
// 如果啟用了滴答定時器功能，則初始化滴答相關指標為NULL
#if (OS_CFG_TICK_EN > 0u)
p_tcb->TickNextPtr = (OS_TCB *)0;
p_tcb->TickPrevPtr = (OS_TCB *)0;
#endif
// 如果啟用了除錯功能，則初始化任務名稱指標為預設值
#if (OS_CFG_DBG_EN > 0u)
p_tcb->NamePtr = (CPU_CHAR *)((void *)"?Task");
#endif
// 如果啟用了除錯功能或棧檢查功能，則初始化棧基址指標為NULL
#if ((OS_CFG_DBG_EN > 0u) || (OS_CFG_STAT_TASK_STK_CHK_EN > 0u))
p_tcb->StkBasePtr = (CPU_STK *)0;
#endif
// 如果啟用了除錯功能，則初始化任務入口地址和引數為0
#if (OS_CFG_DBG_EN > 0u)
p_tcb->TaskEntryAddr = (OS_TASK_PTR)0;
p_tcb->TaskEntryArg = (void *)0;
#endif
// 如果啟用了時間戳功能，則初始化時間戳為0
#if (OS_CFG_TS_EN > 0u)
p_tcb->TS = 0u;
#endif
// 如果啟用了訊息功能，則初始化訊息指標和大小為0
#if (OS_MSG_EN > 0u)
p_tcb->MsgPtr = (void *)0;
p_tcb->MsgSize = 0u;
#endif
// 如果啟用了任務佇列功能，則初始化訊息佇列
#if (OS_CFG_TASK_Q_EN > 0u)
OS_MsgQInit(&p_tcb->MsgQ,
0u);
// 如果啟用了任務分析功能，則初始化訊息佇列相關時間統計為0
#if (OS_CFG_TASK_PROFILE_EN > 0u)
p_tcb->MsgQPendTime = 0u;
p_tcb->MsgQPendTimeMax = 0u;
#endif
#endif
// 如果啟用了標誌功能，則初始化標誌相關變數為0
#if (OS_CFG_FLAG_EN > 0u)
p_tcb->FlagsPend = 0u;
p_tcb->FlagsOpt = 0u;
p_tcb->FlagsRdy = 0u;
#endif
// 如果啟用了任務暫存器表功能，則初始化暫存器表為0
#if (OS_CFG_TASK_REG_TBL_SIZE > 0u)
for (reg_id = 0u; reg_id < OS_CFG_TASK_REG_TBL_SIZE; reg_id++)
{
p_tcb->RegTbl[reg_id] = 0u;
}
#endif
// 如果定義了執行緒區域性儲存表大小且大於0，則初始化TLS表為0
#if defined(OS_CFG_TLS_TBL_SIZE) && (OS_CFG_TLS_TBL_SIZE > 0u)
for (id = 0u; id < OS_CFG_TLS_TBL_SIZE; id++)
{
p_tcb->TLS_Tbl[id] = 0u;
}
#endif
// 初始化訊號量計數器為0
p_tcb->SemCtr = 0u;
// 如果啟用了任務分析功能，則初始化訊號量相關時間統計為0
#if (OS_CFG_TASK_PROFILE_EN > 0u)
p_tcb->SemPendTime = 0u;
p_tcb->SemPendTimeMax = 0u;
#endif
// 如果啟用了除錯功能或棧檢查功能，則初始化棧大小為0
#if ((OS_CFG_DBG_EN > 0u) || (OS_CFG_STAT_TASK_STK_CHK_EN > 0u))
p_tcb->StkSize = 0u;
#endif
// 如果啟用了任務掛起功能，則初始化掛起計數器為0
#if (OS_CFG_TASK_SUSPEND_EN > 0u)
p_tcb->SuspendCtr = 0u;
#endif
// 如果啟用了棧使用情況統計功能，則初始化相關統計變數為0
#if (OS_CFG_STAT_TASK_STK_CHK_EN > 0u)
p_tcb->StkFree = 0u;
p_tcb->StkUsed = 0u;
#endif
// 初始化選項變數為0
p_tcb->Opt = 0u;
// 如果啟用了滴答定時器功能，則初始化滴答相關變數為0
#if (OS_CFG_TICK_EN > 0u)
p_tcb->TickRemain = 0u;
p_tcb->TickCtrPrev = 0u;
#endif
// 如果啟用了輪轉排程功能，則初始化時間片和時間片計數器為0
#if (OS_CFG_SCHED_ROUND_ROBIN_EN > 0u)
p_tcb->TimeQuanta = 0u;
p_tcb->TimeQuantaCtr = 0u;
#endif
// 如果啟用了任務分析功能，則初始化CPU使用率和最大使用率及相關計數器為0
#if (OS_CFG_TASK_PROFILE_EN > 0u)
p_tcb->CPUUsage = 0u;
p_tcb->CPUUsageMax = 0u;
p_tcb->CtxSwCtr = 0u;
p_tcb->CyclesDelta = 0u;
// 如果啟用了時間戳功能，則讀取當前時間戳並儲存
#if (OS_CFG_TS_EN > 0u)
p_tcb->CyclesStart = OS_TS_GET(); /* Read the current timestamp and save */
#else
p_tcb->CyclesStart = 0u;
#endif
p_tcb->CyclesTotal = 0u;
#endif
// 如果定義了中斷禁用測量功能，則初始化最大中斷禁用時間為0
#ifdef CPU_CFG_INT_DIS_MEAS_EN
p_tcb->IntDisTimeMax = 0u;
#endif
// 如果啟用了排程鎖時間測量功能，則初始化最大排程鎖時間為0
#if (OS_CFG_SCHED_LOCK_TIME_MEAS_EN > 0u)
p_tcb->SchedLockTimeMax = 0u;
#endif
// 初始化掛起連結串列的前後指標和掛起物件指標及掛起狀態為初始值
p_tcb->PendNextPtr = (OS_TCB *)0;
p_tcb->PendPrevPtr = (OS_TCB *)0;
p_tcb->PendObjPtr = (OS_PEND_OBJ *)0;
p_tcb->PendOn = OS_TASK_PEND_ON_NOTHING;
p_tcb->PendStatus = OS_STATUS_PEND_OK;
// 初始化任務狀態為就緒
p_tcb->TaskState = OS_TASK_STATE_RDY;
// 初始化任務優先順序為初始值
p_tcb->Prio = OS_PRIO_INIT;
// 如果啟用了互斥鎖功能，則初始化基優先順序和互斥鎖組頭指標為初始值
#if (OS_CFG_MUTEX_EN > 0u)
p_tcb->BasePrio = OS_PRIO_INIT;
p_tcb->MutexGrpHeadPtr = (OS_MUTEX *)0;
#endif
// 如果啟用了除錯功能，則初始化除錯連結串列的前後指標和除錯名稱指標為初始值
#if (OS_CFG_DBG_EN > 0u)
p_tcb->DbgPrevPtr = (OS_TCB *)0;
p_tcb->DbgNextPtr = (OS_TCB *)0;
p_tcb->DbgNamePtr = (CPU_CHAR *)((void *)" ");
#endif
}
/*
************************************************************************************************************************
* CATCH ACCIDENTAL TASK RETURN
*
* Description: This function is called if a task accidentally returns without deleting itself. In other words, a task
* should either be an infinite loop or delete itself if it's done.
*
* Arguments : none
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
/**
* @brief 任務返回函式
*
* 當一個任務需要返回時呼叫此函式。其主要目的是處理不應該正常返回的任務。
* 首先呼叫一個鉤子函式，允許使用者決定如何處理。如果啟用了任務刪除功能，它會嘗試刪除任務。
* 如果未啟用任務刪除功能，它將進入一個帶有延遲的無限迴圈，以防止任務消耗CPU資源。
*/
void OS_TaskReturn(void)
{
OS_ERR err;
OSTaskReturnHook(OSTCBCurPtr); /* 呼叫鉤子函式，讓使用者決定如何處理 */
#if (OS_CFG_TASK_DEL_EN > 0u)
/* 如果啟用了任務刪除功能，刪除當前任務 */
OSTaskDel((OS_TCB *)0,
&err);
#else
/* 如果未啟用任務刪除功能，進入一個帶有延遲的無限迴圈 */
for (;;)
{
OSTimeDly(OSCfg_TickRate_Hz,
OS_OPT_TIME_DLY,
&err);
}
#endif
}
/*
************************************************************************************************************************
* CHECK THE STACK REDZONE OF A TASK
*
* Description: Verify a task's stack redzone.
*
* Arguments : p_tcb is a pointer to the base of the stack.
*
* stk_size is the size of the stack.
*
* Returns : If the stack is corrupted (OS_FALSE) or not (OS_TRUE).
*
* Note(s) : 1) This function is INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u)
CPU_BOOLEAN OS_TaskStkRedzoneChk(CPU_STK *p_base,
CPU_STK_SIZE stk_size)
{
CPU_INT32U i;
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO)
(void)stk_size; /* Prevent compiler warning for not using 'stk_size' */
for (i = 0u; i < OS_CFG_TASK_STK_REDZONE_DEPTH; i++)
{
if (*p_base != (CPU_DATA)OS_STACK_CHECK_VAL)
{
return (OS_FALSE);
}
p_base++;
}
#else
p_base = p_base + stk_size - 1u;
for (i = 0u; i < OS_CFG_TASK_STK_REDZONE_DEPTH; i++)
{
if (*p_base != (CPU_DATA)OS_STACK_CHECK_VAL)
{
return (OS_FALSE);
}
p_base--;
}
#endif
return (OS_TRUE);
}
#endif
/*
************************************************************************************************************************
* INITIALIZE A REDZONE ENABLED STACK
*
* Description: This functions is used to initialize a stack with Redzone checking.
*
* Arguments : p_tcb is a pointer to the base of the stack.
*
* stk_size is the size of the stack.
*
* Returns : none.
*
* Note(s) : 1) This function is INTERNAL to uC/OS-III and your application should not call it.
************************************************************************************************************************
*/
#if (OS_CFG_TASK_STK_REDZONE_EN > 0u)
void OS_TaskStkRedzoneInit(CPU_STK *p_base,
CPU_STK_SIZE stk_size)
{
CPU_STK_SIZE i;
#if (CPU_CFG_STK_GROWTH == CPU_STK_GROWTH_HI_TO_LO)
(void)stk_size; /* Prevent compiler warning for not using 'stk_size' */
for (i = 0u; i < OS_CFG_TASK_STK_REDZONE_DEPTH; i++)
{
*(p_base + i) = (CPU_DATA)OS_STACK_CHECK_VAL;
}
#else
for (i = 0u; i < OS_CFG_TASK_STK_REDZONE_DEPTH; i++)
{
*(p_base + stk_size - 1u - i) = (CPU_DATA)OS_STACK_CHECK_VAL;
}
#endif
}
#endif
/*
************************************************************************************************************************
* CHANGE PRIORITY OF A TASK
*
* Description: This function is called by the kernel to perform the actual operation of changing a task's priority.
* Priority inheritance is updated if necessary.
*
*
*
* Argument(s): p_tcb is a pointer to the tcb of the task to change the priority.
*
* prio_new is the new priority to give to the task.
*
*
* Returns : none.
*
* Note(s) : 1) This function is INTERNAL to uC/OS-III and your application MUST NOT call it.
************************************************************************************************************************
*/
/**
* @brief 更改任務的優先順序。
*
* 此函式修改指定任務的優先順序，並根據任務的當前狀態更新相關列表和結構。
* 如果任務處於就緒狀態，它會調整就緒列表。如果任務正在等待，它會更新等待列表。
*
* @param p_tcb 指向任務控制塊 (TCB) 的指標。
* @param prio_new 新的任務優先順序。
*/
void OS_TaskChangePrio(OS_TCB *p_tcb, OS_PRIO prio_new)
{
OS_TCB *p_tcb_owner;
#if (OS_CFG_MUTEX_EN > 0u)
OS_PRIO prio_cur;
#endif
do
{
p_tcb_owner = (OS_TCB *)0;
#if (OS_CFG_MUTEX_EN > 0u)
prio_cur = p_tcb->Prio;
#endif
// 根據任務狀態進行不同的處理
switch (p_tcb->TaskState)
{
case OS_TASK_STATE_RDY:
// 從當前優先順序列表中移除任務
OS_RdyListRemove(p_tcb);
// 設定新的任務優先順序
p_tcb->Prio = prio_new;
// 插入新的優先順序
OS_PrioInsert(p_tcb->Prio);
if (p_tcb == OSTCBCurPtr)
{
// 當前任務在就緒列表頭部插入
OS_RdyListInsertHead(p_tcb);
}
else
{
// 其他任務在就緒列表尾部插入
OS_RdyListInsertTail(p_tcb);
}
break;
case OS_TASK_STATE_DLY: // 延遲狀態，只需更改優先順序
case OS_TASK_STATE_SUSPENDED:
case OS_TASK_STATE_DLY_SUSPENDED:
// 設定新的任務優先順序
p_tcb->Prio = prio_new;
break;
case OS_TASK_STATE_PEND:
case OS_TASK_STATE_PEND_TIMEOUT:
case OS_TASK_STATE_PEND_SUSPENDED:
case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
// 設定新的任務優先順序
p_tcb->Prio = prio_new;
// 根據任務等待的物件進行不同的處理
switch (p_tcb->PendOn)
{
case OS_TASK_PEND_ON_FLAG:
case OS_TASK_PEND_ON_Q:
case OS_TASK_PEND_ON_SEM:
// 更新等待列表中的優先順序
OS_PendListChangePrio(p_tcb);
break;
case OS_TASK_PEND_ON_MUTEX:
#if (OS_CFG_MUTEX_EN > 0u)
// 更新等待列表中的優先順序
OS_PendListChangePrio(p_tcb);
// 獲取互斥鎖的所有者任務
p_tcb_owner = ((OS_MUTEX *)((void *)p_tcb->PendObjPtr))->OwnerTCBPtr;
if (prio_cur > prio_new)
{ // 是否提高優先順序
if (p_tcb_owner->Prio <= prio_new)
{ // 是否需要將此優先順序分配給所有者
p_tcb_owner = (OS_TCB *)0;
}
else
{
// 跟蹤互斥鎖任務優先順序繼承
OS_TRACE_MUTEX_TASK_PRIO_INHERIT(p_tcb_owner, prio_new);
}
}
else
{
if (p_tcb_owner->Prio == prio_cur)
{ // 是否需要檢查更低的優先順序
prio_new = OS_MutexGrpPrioFindHighest(p_tcb_owner);
prio_new = (prio_new > p_tcb_owner->BasePrio) ? p_tcb_owner->BasePrio : prio_new;
if (prio_new == p_tcb_owner->Prio)
{
p_tcb_owner = (OS_TCB *)0;
}
else
{
// 跟蹤互斥鎖任務優先順序取消繼承
OS_TRACE_MUTEX_TASK_PRIO_DISINHERIT(p_tcb_owner, prio_new);
}
}
else
{
p_tcb_owner = (OS_TCB *)0;
}
}
#endif
break;
case OS_TASK_PEND_ON_TASK_Q:
case OS_TASK_PEND_ON_TASK_SEM:
default:
// 預設情況
break;
}
break;
default:
return;
}
p_tcb = p_tcb_owner;
} while (p_tcb != (OS_TCB *)0);
}