diff --git a/include/nuttx/mutex.h b/include/nuttx/mutex.h new file mode 100644 index 0000000000..7598983954 --- /dev/null +++ b/include/nuttx/mutex.h @@ -0,0 +1,228 @@ +/**************************************************************************** + * include/nuttx/mutex.h + * + * Copyright (C) 2017 Pinecone Inc. All rights reserved. + * Author: Qian Wenfa + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * 3. Neither the name NuttX nor the names of its contributors may be + * used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_MUTEX_H +#define __INCLUDE_NUTTX_MUTEX_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +#define MUTEX_INITIALIZER SEM_INITIALIZER(1); + +/**************************************************************************** + * Public Type Definitions + ****************************************************************************/ + +typedef sem_t mutex_t; + +/**************************************************************************** + * Public Function Prototypes + ****************************************************************************/ + +#ifndef __ASSEMBLY__ + +#ifdef __cplusplus +#define EXTERN extern "C" +extern "C" +{ +#else +#define EXTERN extern +#endif + +/**************************************************************************** + * Name: nxmutex_init + * + * Description: + * This function initializes the UNAMED mutex. Following a + * successful call to nxmutex_init(), the mutex may be used in subsequent + * calls to nxmutex_lock(), nxmutex_unlock(), and nxmutex_trylock(). The mutex + * remains usable until it is destroyed. + * + * Parameters: + * mutex - Semaphore to be initialized + * + * Return Value: + * This is an internal OS interface and should not be used by applications. + * It follows the NuttX internal error return policy: Zero (OK) is + * returned on success. A negated errno value is returned on failure. + * + ****************************************************************************/ + +static inline int nxmutex_init(FAR mutex_t *mutex) +{ + return nxsem_init(mutex, 0, 1); +} + +/**************************************************************************** + * Name: nxmutex_destroy + * + * Description: + * This function initializes the UNAMED mutex. Following a + * successful call to nxmutex_init(), the mutex may be used in subsequent + * calls to nxmutex_lock(), nxmutex_unlock(), and nxmutex_trylock(). The mutex + * remains usable until it is destroyed. + * + * Parameters: + * mutex - Semaphore to be destroyed + * + * Return Value: + * This is an internal OS interface and should not be used by applications. + * It follows the NuttX internal error return policy: Zero (OK) is + * returned on success. A negated errno value is returned on failure. + * + ****************************************************************************/ + +static inline int nxmutex_destroy(FAR mutex_t *mutex) +{ + return nxsem_destroy(mutex); +} + +/**************************************************************************** + * Name: nxmutex_lock + * + * Description: + * This function attempts to lock the mutex referenced by 'mutex'. The mutex + * is implemented with a semaphore, so if the semaphore value is (<=) zero, + * then the calling task will not return until it successfully acquires the lock. + * + * Parameters: + * mutex - mutex descriptor. + * + * Return Value: + * This is an internal OS interface and should not be used by applications. + * It follows the NuttX internal error return policy: Zero (OK) is + * returned on success. A negated errno value is returned on failure. + * Possible returned errors: + * + ****************************************************************************/ + +static inline int nxmutex_lock(FAR mutex_t *mutex) +{ + return nxsem_wait_uninterruptible(mutex); +} + +/**************************************************************************** + * Name: nxmutex_trylock + * + * Description: + * This function locks the mutex only if the mutex is currently not locked. + * If the mutex has been locked already, the call returns without blocking. + * + * Parameters: + * mutex - mutex descriptor. + * + * Return Value: + * This is an internal OS interface and should not be used by applications. + * It follows the NuttX internal error return policy: Zero (OK) is + * returned on success. A negated errno value is returned on failure. + * Possible returned errors: + * + * -EINVAL - Invalid attempt to lock the mutex + * -EAGAIN - The mutex is not available. + * + ****************************************************************************/ + +static inline int nxmutex_trylock(FAR mutex_t *mutex) +{ + return nxsem_trywait(mutex); +} + +/**************************************************************************** + * Name: nxmutex_is_locked + * + * Description: + * This function get the lock state the mutex referenced by 'mutex'. + * + * Parameters: + * mutex - mutex descriptor. + * + * Return Value: + * + ****************************************************************************/ + +static inline bool nxmutex_is_locked(FAR mutex_t *mutex) +{ + int cnt; + int ret; + + ret = nxsem_getvalue(mutex, &cnt); + + DEBUGASSERT(ret == OK); + + return cnt < 1; +} + +/**************************************************************************** + * Name: nxmutex_unlock + * + * Description: + * This function attempts to unlock the mutex referenced by 'mutex'. + * + * Parameters: + * mutex - mutex descriptor. + * + * Return Value: + * This is an internal OS interface and should not be used by applications. + * It follows the NuttX internal error return policy: Zero (OK) is + * returned on success. A negated errno value is returned on failure. + * Possible returned errors: + * + * Assumptions: + * This function may be called from an interrupt handler. + * + ****************************************************************************/ + +static inline int nxmutex_unlock(FAR mutex_t *mutex) +{ + return nxsem_post(mutex); +} + +#undef EXTERN +#ifdef __cplusplus +} +#endif + +#endif /* __ASSEMBLY__ */ +#endif /* __INCLUDE_NUTTX_MUTEX_H */