395 lines
12 KiB
C
395 lines
12 KiB
C
/*
|
|
* Copyright (c) 1997-2015 Wind River Systems, Inc.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* @brief mutex kernel services
|
|
*
|
|
* This module contains routines for handling mutex locking and unlocking. It
|
|
* also includes routines that force the release of mutex objects when a task
|
|
* is aborted or unloaded.
|
|
*
|
|
* Mutexes implement a priority inheritance algorithm that boosts the priority
|
|
* level of the owning task to match the priority level of the highest priority
|
|
* task waiting on the mutex.
|
|
*
|
|
* Each mutex that contributes to priority inheritance must be released in the
|
|
* reverse order in which is was acquired. Furthermore each subsequent mutex
|
|
* that contributes to raising the owning task's priority level must be acquired
|
|
* at a point after the most recent "bumping" of the priority level.
|
|
*
|
|
* For example, if task A has two mutexes contributing to the raising of its
|
|
* priority level, the second mutex M2 must be acquired by task A after task
|
|
* A's priority level was bumped due to owning the first mutex M1. When
|
|
* releasing the mutex, task A must release M2 before it releases M1. Failure
|
|
* to follow this nested model may result in tasks running at unexpected priority
|
|
* levels (too high, or too low).
|
|
*/
|
|
|
|
#include <microkernel.h>
|
|
#include <micro_private.h>
|
|
#include <nano_private.h>
|
|
|
|
/**
|
|
* @brief Reply to a mutex lock request.
|
|
*
|
|
* This routine replies to a mutex lock request. This will occur if either
|
|
* the waiting task times out or acquires the mutex lock.
|
|
*
|
|
* @param A k_args
|
|
*
|
|
* @return N/A
|
|
*/
|
|
void _k_mutex_lock_reply(
|
|
struct k_args *A /* pointer to mutex lock reply request arguments */
|
|
)
|
|
{
|
|
#ifdef CONFIG_SYS_CLOCK_EXISTS
|
|
struct _k_mutex_struct *Mutex; /* pointer to internal mutex structure */
|
|
struct k_args *PrioChanger; /* used to change a task's priority level */
|
|
struct k_args *FirstWaiter; /* pointer to first task in wait queue */
|
|
kpriority_t newPriority; /* priority level to which to drop */
|
|
int MutexId; /* mutex ID obtained from request args */
|
|
|
|
if (A->Time.timer) {
|
|
FREETIMER(A->Time.timer);
|
|
}
|
|
|
|
if (A->Comm == _K_SVC_MUTEX_LOCK_REPLY_TIMEOUT) {/* Timeout case */
|
|
|
|
REMOVE_ELM(A);
|
|
A->Time.rcode = RC_TIME;
|
|
|
|
MutexId = A->args.l1.mutex;
|
|
Mutex = (struct _k_mutex_struct *)MutexId;
|
|
|
|
FirstWaiter = Mutex->waiters;
|
|
|
|
/*
|
|
* When timing out, there are two cases to consider.
|
|
* 1. There are no waiting tasks.
|
|
* - As there are no waiting tasks, this mutex is no longer
|
|
* involved in priority inheritance. It's current priority
|
|
* level should be dropped (if needed) to the original
|
|
* priority level.
|
|
* 2. There is at least one waiting task in a priority ordered
|
|
* list.
|
|
* - Depending upon the the priority level of the first
|
|
* waiting task, the owner task's original priority and
|
|
* the ceiling priority, the owner's priority level may
|
|
* be dropped but not necessarily to the original priority
|
|
* level.
|
|
*/
|
|
|
|
newPriority = Mutex->original_owner_priority;
|
|
|
|
if (FirstWaiter != NULL) {
|
|
newPriority = (FirstWaiter->priority < newPriority)
|
|
? FirstWaiter->priority
|
|
: newPriority;
|
|
newPriority = (newPriority > CONFIG_PRIORITY_CEILING)
|
|
? newPriority
|
|
: CONFIG_PRIORITY_CEILING;
|
|
}
|
|
|
|
if (Mutex->current_owner_priority != newPriority) {
|
|
GETARGS(PrioChanger);
|
|
PrioChanger->alloc = true;
|
|
PrioChanger->Comm = _K_SVC_TASK_PRIORITY_SET;
|
|
PrioChanger->priority = newPriority;
|
|
PrioChanger->args.g1.task = Mutex->owner;
|
|
PrioChanger->args.g1.prio = newPriority;
|
|
SENDARGS(PrioChanger);
|
|
Mutex->current_owner_priority = newPriority;
|
|
}
|
|
} else {/* LOCK_RPL: Reply case */
|
|
A->Time.rcode = RC_OK;
|
|
}
|
|
#else
|
|
/* LOCK_RPL: Reply case */
|
|
A->Time.rcode = RC_OK;
|
|
#endif
|
|
|
|
_k_state_bit_reset(A->Ctxt.task, TF_LOCK);
|
|
}
|
|
|
|
/**
|
|
* @brief Reply to a mutex lock request with timeout.
|
|
*
|
|
* This routine replies to a mutex lock request. This will occur if either
|
|
* the waiting task times out or acquires the mutex lock.
|
|
*
|
|
* @param A Pointer to a k_args structure.
|
|
*
|
|
* @return N/A
|
|
*/
|
|
void _k_mutex_lock_reply_timeout(struct k_args *A)
|
|
{
|
|
_k_mutex_lock_reply(A);
|
|
}
|
|
|
|
/**
|
|
* @brief Process a mutex lock request
|
|
*
|
|
* This routine processes a mutex lock request (LOCK_REQ). If the mutex
|
|
* is already locked, and the timeout is non-zero then the priority inheritance
|
|
* algorithm may be applied to prevent priority inversion scenarios.
|
|
*
|
|
* @param A k_args
|
|
*
|
|
* @return N/A
|
|
*/
|
|
void _k_mutex_lock_request(struct k_args *A /* pointer to mutex lock
|
|
* request arguments
|
|
*/
|
|
)
|
|
{
|
|
struct _k_mutex_struct *Mutex; /* pointer to internal mutex structure */
|
|
int MutexId; /* mutex ID obtained from lock request */
|
|
struct k_args *PrioBooster; /* used to change a task's priority level */
|
|
kpriority_t BoostedPrio; /* new "boosted" priority level */
|
|
|
|
MutexId = A->args.l1.mutex;
|
|
|
|
|
|
Mutex = (struct _k_mutex_struct *)MutexId;
|
|
if (Mutex->level == 0 || Mutex->owner == A->args.l1.task) {
|
|
/* The mutex is either unowned or this is a nested lock. */
|
|
#ifdef CONFIG_OBJECT_MONITOR
|
|
Mutex->count++;
|
|
#endif
|
|
|
|
Mutex->owner = A->args.l1.task;
|
|
|
|
/*
|
|
* Assign the current owner's priority from the priority found
|
|
* in the current task's task object: the priority stored there
|
|
* may be more recent than the one stored in struct k_args.
|
|
*/
|
|
Mutex->current_owner_priority = _k_current_task->priority;
|
|
|
|
/*
|
|
* Save the original priority when first acquiring the lock (but
|
|
* not on nested locks). The original priority level only
|
|
* reflects the priority level of the requesting task at the
|
|
* time the lock is acquired. Consequently, if the requesting
|
|
* task is already involved in priority inheritance, this
|
|
* original priority reflects its "boosted" priority.
|
|
*/
|
|
if (Mutex->level == 0) {
|
|
Mutex->original_owner_priority = Mutex->current_owner_priority;
|
|
}
|
|
|
|
Mutex->level++;
|
|
|
|
A->Time.rcode = RC_OK;
|
|
|
|
} else {
|
|
/* The mutex is owned by another task. */
|
|
#ifdef CONFIG_OBJECT_MONITOR
|
|
Mutex->num_conflicts++;
|
|
#endif
|
|
|
|
if (likely(A->Time.ticks != TICKS_NONE)) {
|
|
/*
|
|
* A non-zero timeout was specified. Ensure the
|
|
* priority saved in the request is up to date
|
|
*/
|
|
A->Ctxt.task = _k_current_task;
|
|
A->priority = _k_current_task->priority;
|
|
_k_state_bit_set(_k_current_task, TF_LOCK);
|
|
/* Note: Mutex->waiters is a priority sorted list */
|
|
INSERT_ELM(Mutex->waiters, A);
|
|
#ifdef CONFIG_SYS_CLOCK_EXISTS
|
|
if (A->Time.ticks == TICKS_UNLIMITED) {
|
|
/* Request will not time out */
|
|
A->Time.timer = NULL;
|
|
} else {
|
|
/*
|
|
* Prepare to call _k_mutex_lock_reply() should
|
|
* the request time out.
|
|
*/
|
|
A->Comm = _K_SVC_MUTEX_LOCK_REPLY_TIMEOUT;
|
|
_k_timeout_alloc(A);
|
|
}
|
|
#endif
|
|
if (A->priority < Mutex->current_owner_priority) {
|
|
/*
|
|
* The priority level of the owning task is less
|
|
* than that of the requesting task. Boost the
|
|
* priority level of the owning task to match
|
|
* the priority level of the requesting task.
|
|
* Note that the boosted priority level is
|
|
* limited to <K_PrioCeiling>.
|
|
*/
|
|
BoostedPrio = (A->priority > CONFIG_PRIORITY_CEILING)
|
|
? A->priority
|
|
: CONFIG_PRIORITY_CEILING;
|
|
if (BoostedPrio < Mutex->current_owner_priority) {
|
|
/* Boost the priority level */
|
|
GETARGS(PrioBooster);
|
|
|
|
PrioBooster->alloc = true;
|
|
PrioBooster->Comm = _K_SVC_TASK_PRIORITY_SET;
|
|
PrioBooster->priority = BoostedPrio;
|
|
PrioBooster->args.g1.task = Mutex->owner;
|
|
PrioBooster->args.g1.prio = BoostedPrio;
|
|
SENDARGS(PrioBooster);
|
|
Mutex->current_owner_priority = BoostedPrio;
|
|
}
|
|
}
|
|
} else {
|
|
/*
|
|
* ERROR. The mutex is locked by another task and
|
|
* this is an immediate lock request (timeout = 0).
|
|
*/
|
|
A->Time.rcode = RC_FAIL;
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @brief Mutex lock kernel service
|
|
*
|
|
* This routine is the entry to the mutex lock kernel service.
|
|
*
|
|
* @param mutex Mutex object
|
|
* @param time The maximum Timeout value (in ticks)
|
|
*
|
|
* @return RC_OK on success, RC_FAIL on error, RC_TIME on timeout
|
|
*/
|
|
int _task_mutex_lock(kmutex_t mutex, int32_t time)
|
|
{
|
|
struct k_args A; /* argument packet */
|
|
|
|
A.Comm = _K_SVC_MUTEX_LOCK_REQUEST;
|
|
A.Time.ticks = time;
|
|
A.args.l1.mutex = mutex;
|
|
A.args.l1.task = _k_current_task->id;
|
|
KERNEL_ENTRY(&A);
|
|
return A.Time.rcode;
|
|
}
|
|
|
|
/**
|
|
* @brief Process a mutex unlock request
|
|
*
|
|
* This routine processes a mutex unlock request (UNLOCK). If the mutex
|
|
* was involved in priority inheritance, then it will change the priority level
|
|
* of the current owner to the priority level it had when it acquired the
|
|
* mutex.
|
|
*
|
|
* @param A pointer to mutex unlock request arguments
|
|
*
|
|
* @return N/A
|
|
*/
|
|
void _k_mutex_unlock(struct k_args *A)
|
|
{
|
|
struct _k_mutex_struct *Mutex; /* pointer internal mutex structure */
|
|
int MutexId; /* mutex ID obtained from unlock request */
|
|
struct k_args *PrioDowner; /* used to change a task's priority level */
|
|
|
|
MutexId = A->args.l1.mutex;
|
|
Mutex = (struct _k_mutex_struct *)MutexId;
|
|
if (Mutex->owner == A->args.l1.task && --(Mutex->level) == 0) {
|
|
/*
|
|
* The requesting task owns the mutex and all locks
|
|
* have been released.
|
|
*/
|
|
|
|
struct k_args *X;
|
|
|
|
#ifdef CONFIG_OBJECT_MONITOR
|
|
Mutex->count++;
|
|
#endif
|
|
|
|
if (Mutex->current_owner_priority != Mutex->original_owner_priority) {
|
|
/*
|
|
* This mutex is involved in priority inheritance.
|
|
* Send a request to revert the priority level of
|
|
* the owning task back to its priority level when
|
|
* it first acquired the mutex.
|
|
*/
|
|
GETARGS(PrioDowner);
|
|
|
|
PrioDowner->alloc = true;
|
|
PrioDowner->Comm = _K_SVC_TASK_PRIORITY_SET;
|
|
PrioDowner->priority = Mutex->original_owner_priority;
|
|
PrioDowner->args.g1.task = Mutex->owner;
|
|
PrioDowner->args.g1.prio = Mutex->original_owner_priority;
|
|
SENDARGS(PrioDowner);
|
|
}
|
|
|
|
X = Mutex->waiters;
|
|
if (X != NULL) {
|
|
/*
|
|
* At least one task was waiting for the mutex.
|
|
* Assign the new owner of the task to be the
|
|
* first in the queue.
|
|
*/
|
|
|
|
Mutex->waiters = X->next;
|
|
Mutex->owner = X->args.l1.task;
|
|
Mutex->level = 1;
|
|
Mutex->current_owner_priority = X->priority;
|
|
Mutex->original_owner_priority = X->priority;
|
|
|
|
#ifdef CONFIG_SYS_CLOCK_EXISTS
|
|
if (X->Time.timer) {
|
|
/*
|
|
* Trigger a call to _k_mutex_lock_reply()--it
|
|
* will send a reply with a return code of
|
|
* RC_OK.
|
|
*/
|
|
_k_timeout_cancel(X);
|
|
X->Comm = _K_SVC_MUTEX_LOCK_REPLY;
|
|
} else {
|
|
#endif
|
|
/*
|
|
* There is no timer to update.
|
|
* Set the return code.
|
|
*/
|
|
X->Time.rcode = RC_OK;
|
|
_k_state_bit_reset(X->Ctxt.task, TF_LOCK);
|
|
#ifdef CONFIG_SYS_CLOCK_EXISTS
|
|
}
|
|
#endif
|
|
} else {
|
|
/* No task is waiting in the queue. */
|
|
Mutex->owner = ANYTASK;
|
|
Mutex->level = 0;
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @brief Mutex unlock kernel service
|
|
*
|
|
* This routine is the entry to the mutex unlock kernel service.
|
|
*
|
|
* @param mutex mutex to unlock
|
|
*
|
|
* @return N/A
|
|
*/
|
|
void _task_mutex_unlock(kmutex_t mutex)
|
|
{
|
|
struct k_args A; /* argument packet */
|
|
|
|
A.Comm = _K_SVC_MUTEX_UNLOCK;
|
|
A.args.l1.mutex = mutex;
|
|
A.args.l1.task = _k_current_task->id;
|
|
KERNEL_ENTRY(&A);
|
|
}
|