/**
* \b atomSemTimerCallback
*
* This is an internal function not for use by application code.
*
* Timeouts on suspended threads are notified by the timer system through
* this generic callback. The timer system calls us back with a pointer to
* the relevant \c SEM_TIMER object which is used to retrieve the
* semaphore details.
*
* @param[in] cb_data Pointer to a SEM_TIMER object
*/
static void atomSemTimerCallback (POINTER cb_data)
{
SEM_TIMER *timer_data_ptr;
CRITICAL_STORE;
/* Get the SEM_TIMER structure pointer */
timer_data_ptr = (SEM_TIMER *)cb_data;
/* Check parameter is valid */
if (timer_data_ptr)
{
/* Enter critical region */
CRITICAL_START ();
/* Set status to indicate to the waiting thread that it timed out */
timer_data_ptr->tcb_ptr->suspend_wake_status = ATOM_TIMEOUT;
/* Flag as no timeout registered */
timer_data_ptr->tcb_ptr->suspend_timo_cb = NULL;
/* Remove this thread from the semaphore's suspend list */
(void)tcbDequeueEntry (&timer_data_ptr->sem_ptr->suspQ, timer_data_ptr->tcb_ptr);
/* Put the thread on the ready queue */
(void)tcbEnqueuePriority (&tcbReadyQ, timer_data_ptr->tcb_ptr);
/* Exit critical region */
CRITICAL_END ();
/**
* Note that we don't call the scheduler now as it will be called
* when we exit the ISR by atomIntExit().
*/
}
}
/**
* \b atomSemGet
*
* Perform a get operation on a semaphore.
*
* This decrements the current count value for the semaphore and returns.
* If the count value is already zero then the call will block until the
* count is incremented by another thread, or until the specified \c timeout
* is reached. Blocking threads will also be woken if the semaphore is
* deleted by another thread while blocking.
*
* Depending on the \c timeout value specified the call will do one of
* the following if the count value is zero:
*
* \c timeout == 0 : Call will block until the count is non-zero \n
* \c timeout > 0 : Call will block until non-zero up to the specified timeout \n
* \c timeout == -1 : Return immediately if the count is zero \n
*
* If the call needs to block and \c timeout is zero, it will block
* indefinitely until atomSemPut() or atomSemDelete() is called on the
* semaphore.
*
* If the call needs to block and \c timeout is non-zero, the call will only
* block for the specified number of system ticks after which time, if the
* thread was not already woken, the call will return with \c ATOM_TIMEOUT.
*
* If the call would normally block and \c timeout is -1, the call will
* return immediately with \c ATOM_WOULDBLOCK.
*
* This function can only be called from interrupt context if the \c timeout
* parameter is -1 (in which case it does not block).
*
* @param[in] sem Pointer to semaphore object
* @param[in] timeout Max system ticks to block (0 = forever)
*
* @retval ATOM_OK Success
* @retval ATOM_TIMEOUT Semaphore timed out before being woken
* @retval ATOM_WOULDBLOCK Called with timeout == -1 but count is zero
* @retval ATOM_ERR_DELETED Semaphore was deleted while suspended
* @retval ATOM_ERR_CONTEXT Not called in thread context and attempted to block
* @retval ATOM_ERR_PARAM Bad parameter
* @retval ATOM_ERR_QUEUE Problem putting the thread on the suspend queue
* @retval ATOM_ERR_TIMER Problem registering the timeout
*/
uint8_t atomSemGet (ATOM_SEM *sem, int32_t timeout)
{
CRITICAL_STORE;
uint8_t status;
SEM_TIMER timer_data;
ATOM_TIMER timer_cb;
ATOM_TCB *curr_tcb_ptr;
/* Check parameters */
if (sem == NULL)
{
/* Bad semaphore pointer */
status = ATOM_ERR_PARAM;
}
else
{
/* Protect access to the semaphore object and OS queues */
CRITICAL_START ();
/* If count is zero, block the calling thread */
if (sem->count == 0)
{
/* If called with timeout >= 0, we should block */
if (timeout >= 0)
{
/* Count is zero, block the calling thread */
/* Get the current TCB */
curr_tcb_ptr = atomCurrentContext();
/* Check we are actually in thread context */
if (curr_tcb_ptr)
{
/* Add current thread to the suspend list on this semaphore */
if (tcbEnqueuePriority (&sem->suspQ, curr_tcb_ptr) != ATOM_OK)
{
/* Exit critical region */
CRITICAL_END ();
/* There was an error putting this thread on the suspend list */
status = ATOM_ERR_QUEUE;
}
else
{
/* Set suspended status for the current thread */
curr_tcb_ptr->suspended = TRUE;
/* Track errors */
status = ATOM_OK;
/* Register a timer callback if requested */
if (timeout)
{
/* Fill out the data needed by the callback to wake us up */
timer_data.tcb_ptr = curr_tcb_ptr;
timer_data.sem_ptr = sem;
/* Fill out the timer callback request structure */
timer_cb.cb_func = atomSemTimerCallback;
timer_cb.cb_data = (POINTER)&timer_data;
timer_cb.cb_ticks = timeout;
/**
* Store the timer details in the TCB so that we can
* cancel the timer callback if the semaphore is put
* before the timeout occurs.
*/
curr_tcb_ptr->suspend_timo_cb = &timer_cb;
/* Register a callback on timeout */
if (atomTimerRegister (&timer_cb) != ATOM_OK)
{
/* Timer registration failed */
status = ATOM_ERR_TIMER;
/* Clean up and return to the caller */
(void)tcbDequeueEntry (&sem->suspQ, curr_tcb_ptr);
curr_tcb_ptr->suspended = FALSE;
curr_tcb_ptr->suspend_timo_cb = NULL;
}
}
/* Set no timeout requested */
else
{
/* No need to cancel timeouts on this one */
curr_tcb_ptr->suspend_timo_cb = NULL;
}
/* Exit critical region */
CRITICAL_END ();
/* Check no errors have occurred */
if (status == ATOM_OK)
{
/**
* Current thread now blocking, schedule in a new
* one. We already know we are in thread context
* so can call the scheduler from here.
*/
atomSched (FALSE);
/**
* Normal atomSemPut() wakeups will set ATOM_OK status,
* while timeouts will set ATOM_TIMEOUT and semaphore
* deletions will set ATOM_ERR_DELETED.
*/
status = curr_tcb_ptr->suspend_wake_status;
/**
* If we have been woken up with ATOM_OK then
* another thread incremented the semaphore and
* handed control to this thread. In theory the
* the posting thread increments the counter and
* as soon as this thread wakes up we decrement
* the counter here, but to prevent another
* thread preempting this thread and decrementing
* the semaphore before this section was
* scheduled back in, we emulate the increment
* and decrement by not incrementing in the
* atomSemPut() and not decrementing here. The
* count remains zero throughout preventing other
* threads preempting before we decrement the
* count again.
*/
}
}
}
else
{
/* Exit critical region */
CRITICAL_END ();
/* Not currently in thread context, can't suspend */
status = ATOM_ERR_CONTEXT;
}
}
else
{
/* timeout == -1, requested not to block and count is zero */
CRITICAL_END();
status = ATOM_WOULDBLOCK;
}
}
else
{
/* Count is non-zero, just decrement it and return to calling thread */
sem->count--;
/* Exit critical region */
CRITICAL_END ();
/* Successful */
status = ATOM_OK;
}
}
return (status);
}
/**
* \b atomMutexGet
*
* Take the lock on a mutex.
*
* This takes ownership of a mutex if it is not currently owned. Ownership
* is held by this thread until a corresponding call to atomMutexPut() by
* the same thread.
*
* Can be called recursively by the original locking thread (owner).
* Recursive calls are counted, and ownership is not relinquished until
* the number of unlock (atomMutexPut()) calls by the owner matches the
* number of lock (atomMutexGet()) calls.
*
* No thread other than the owner can lock or unlock the mutex while it is
* locked by another thread.
*
* Depending on the \c timeout value specified the call will do one of
* the following if the mutex is already locked by another thread:
*
* \c timeout == 0 : Call will block until the mutex is available \n
* \c timeout > 0 : Call will block until available up to the specified timeout \n
* \c timeout == -1 : Return immediately if mutex is locked by another thread \n
*
* If the call needs to block and \c timeout is zero, it will block
* indefinitely until the owning thread calls atomMutexPut() or
* atomMutexDelete() is called on the mutex.
*
* If the call needs to block and \c timeout is non-zero, the call will only
* block for the specified number of system ticks after which time, if the
* thread was not already woken, the call will return with \c ATOM_TIMEOUT.
*
* If the call would normally block and \c timeout is -1, the call will
* return immediately with \c ATOM_WOULDBLOCK.
*
* This function can only be called from thread context. A mutex has the
* concept of an owner thread, so it is never valid to make a mutex call
* from interrupt context when there is no thread to associate with.
*
* @param[in] mutex Pointer to mutex object
* @param[in] timeout Max system ticks to block (0 = forever)
*
* @retval ATOM_OK Success
* @retval ATOM_TIMEOUT Mutex timed out before being woken
* @retval ATOM_WOULDBLOCK Called with timeout == -1 but count is zero
* @retval ATOM_ERR_DELETED Mutex was deleted while suspended
* @retval ATOM_ERR_CONTEXT Not called in thread context and attempted to block
* @retval ATOM_ERR_PARAM Bad parameter
* @retval ATOM_ERR_QUEUE Problem putting the thread on the suspend queue
* @retval ATOM_ERR_TIMER Problem registering the timeout
* @retval ATOM_ERR_OVF The recursive lock count would have overflowed (>255)
*/
uint8_t atomMutexGet (ATOM_MUTEX *mutex, int32_t timeout){
CRITICAL_STORE;
uint8_t status;
MUTEX_TIMER timer_data;
ATOM_TIMER timer_cb;
ATOM_TCB *curr_tcb_ptr;
/* Check parameters */
if (mutex == NULL)
{
/* Bad mutex pointer */
status = ATOM_ERR_PARAM;
}
else
{
/* Get the current TCB */
curr_tcb_ptr = atomCurrentContext();
/* Protect access to the mutex object and OS queues */
CRITICAL_START ();
/**
* Check we are at thread context. Because mutexes have the concept of
* owner threads, it is never valid to call here from an ISR,
* regardless of whether we will block.
*/
if (curr_tcb_ptr == NULL)
{
/* Exit critical region */
CRITICAL_END ();
/* Not currently in thread context, can't suspend */
status = ATOM_ERR_CONTEXT;
}
/* Otherwise if mutex is owned by another thread, block the calling thread */
else if ((mutex->owner != NULL) && (mutex->owner != curr_tcb_ptr))
{
/* If called with timeout >= 0, we should block */
if (timeout >= 0)
{
/* Add current thread to the suspend list on this mutex */
if (tcbEnqueuePriority (&mutex->suspQ, curr_tcb_ptr) != ATOM_OK)
{
/* Exit critical region */
CRITICAL_END ();
/* There was an error putting this thread on the suspend list */
status = ATOM_ERR_QUEUE;
}
else
{
/* Set suspended status for the current thread */
curr_tcb_ptr->suspended = TRUE;
/* Track errors */
status = ATOM_OK;
/* Register a timer callback if requested */
if (timeout)
{
/* Fill out the data needed by the callback to wake us up */
timer_data.tcb_ptr = curr_tcb_ptr;
timer_data.mutex_ptr = mutex;
/* Fill out the timer callback request structure */
timer_cb.cb_func = atomMutexTimerCallback;
timer_cb.cb_data = (POINTER)&timer_data;
timer_cb.cb_ticks = timeout;
/**
* Store the timer details in the TCB so that we can
* cancel the timer callback if the mutex is put
* before the timeout occurs.
*/
curr_tcb_ptr->suspend_timo_cb = &timer_cb;
/* Register a callback on timeout */
if (atomTimerRegister (&timer_cb) != ATOM_OK)
{
/* Timer registration failed */
status = ATOM_ERR_TIMER;
/* Clean up and return to the caller */
(void)tcbDequeueEntry (&mutex->suspQ, curr_tcb_ptr);
curr_tcb_ptr->suspended = FALSE;
curr_tcb_ptr->suspend_timo_cb = NULL;
}
}
/* Set no timeout requested */
else
{
/* No need to cancel timeouts on this one */
curr_tcb_ptr->suspend_timo_cb = NULL;
}
/* Exit critical region */
CRITICAL_END ();
/* Check no errors have occurred */
if (status == ATOM_OK)
{
/**
* Current thread now blocking, schedule in a new
* one. We already know we are in thread context
* so can call the scheduler from here.
*/
atomSched (FALSE);
/**
* Normal atomMutexPut() wakeups will set ATOM_OK status,
* while timeouts will set ATOM_TIMEOUT and mutex
* deletions will set ATOM_ERR_DELETED. */
status = curr_tcb_ptr->suspend_wake_status;
/**
* If we were woken up by another thread relinquishing
* the mutex and handing this thread ownership, then
* the relinquishing thread will set status to ATOM_OK
* and will make this thread the owner. Setting the
* owner before waking the thread ensures that no other
* thread can preempt and take ownership of the mutex
* between this thread being made ready to run, and
* actually being scheduled back in here.
*/
if (status == ATOM_OK)
{
/**
* Since this thread has just gained ownership, the
* lock count is zero and should be incremented
* once for this call.
*/
mutex->count++;
}
}
}
}
else
{
/* timeout == -1, requested not to block and mutex is owned by another thread */
CRITICAL_END();
status = ATOM_WOULDBLOCK;
}
}
else
{
/* Thread is not owned or is owned by us, we can claim ownership */
/* Increment the lock count, checking for count overflow */
if (mutex->count == 255)
{
/* Don't increment, just return error status */
status = ATOM_ERR_OVF;
}
else
{
/* Increment the count and return to the calling thread */
mutex->count++;
/* If the mutex is not locked, mark the calling thread as the new owner */
if (mutex->owner == NULL)
{
mutex->owner = curr_tcb_ptr;
}
/* Successful */
status = ATOM_OK;
}
/* Exit critical region */
CRITICAL_END ();
}
}
return (status);
}
