Concurrency Models: Operations on Locks

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

Concurrency Models: Operations on Locks

Purpose

Models for lock acquisition and lock release operations support concurrency checking in CodeSonar.

Other Factors

Lock acquisition and release operations often interact with other code artifacts in ways that themselves need to be accounted for.

Wrapper Functions	If your code acquires and releases locks via wrapper functions that (directly or indirectly) call modeled functions, use configuration parameters LOCK_FUNCTIONS and UNLOCK_FUNCTIONS to identify the wrappers. This instructs CodeSonar to report lock-related issues at the locations where the wrappers are used, rather then inside the wrapper function body.
Failure Behavior	The lock acquisition and release models shipped with CodeSonar model the failure cases of the corresponding library functions. If you want the analysis to assume these operations will never fail, set MUTEX_FAILURE_BEHAVIOR = DOESNT_FAIL in your configuration file. If you are creating a lock operation model that does not just call an existing model, failure cases are one of the factors you will need to account for.
Named Semaphores	CodeSonar treats common semaphore wait functions (such as sem_wait()) as acquiring locks, and semaphore post functions (such as sem_post()) as releasing locks. If your code uses named semaphores as mutexes, use configuration parameter SEMOPEN_FUNCTIONS to identify the functions used to open them. If you are using semaphores for other purposes, such as producer-consumer patterns, you are likely to encounter false-positive warnings when you use these functions. Set the Finding for these warnings to "False Positive" to keep them out of your way. To reduce the incidence of such false-positives, only base your own library models on these functions if you are using the modeled functions for lock management, and only identify functions as SEMOPEN_FUNCTIONS if the resulting semaphores are used as mutexes.

Lock Acquisition Functions

CodeSonar ships with library models that allow it to recognize a number of lock acquisition operators and functions across many different libraries. Some examples are listed below.

	Functions recognized as acquiring locks include...
Apache Portable Runtime (APR)	apr_global_mutex_lock(), apr_thread_mutex_lock()
ARINC 653	LOCK_PREEMPTION()
CMX-RTX	K_Resource_Get(), K_Task_Lock()
FreeRTOS	xQueueSemaphoreTake(), xSemaphoreTakeFromISR()
libc	g_mutex_lock(), sem_wait()
Linux Kernel	__acquire(), down()
Mac OS X	hw_lock_lock(), usimple_lock()
MSVC++ STL	_Lockit::_Lockit()
Win32/MFC	CMutex::Lock()
Netscape Portable Runtime (NSPR)	PR_CEnterMonitor(), PR_Lock()
OpenMP	omp_set_lock(), omp_test_lock()
Qt	QMutex::lock()
ThreadX	tx_mutex_get()
uC/OS-III	OSMutexPend()
VxWorks	kernelLockTake(), semBCreate()
Win32	CCriticalSection::Lock(), EnterCriticalSection()
wxWidgets	wxCriticalSection::Enter(), wxMutex::Lock()

Lock Release Functions

CodeSonar ships with library models that allow it to recognize a number of lock release operators and functions across many different libraries. Some examples are listed below.

	Functions recognized as releasing locks include...
Apache Portable Runtime (APR)	apr_global_mutex_unlock()
ARINC 653	UNLOCK_PREEMPTION()
CMX-RTX	K_Resource_Release()
FreeRTOS	xQueueGiveFromISR()
libc	g_mutex_unlock()
Linux Kernel	__raw_spin_unlock()
Mac OS X	lck_mtx_unlock()
Netscape Portable Runtime (NSPR)	PR_Unlock()
OpenMP	omp_unset_lock()
Qt	QMutex::unlock()
ThreadX	_tx_mutex_put()
uC/OS-III	OSMutexPost()
VxWorks	kernelLockGive()
Win32	CCriticalSection::Unlock()
wxWidgets	wxCriticalSection::Leave()

Condition-Wait Functions

CodeSonar ships with models for several condition-wait functions, including (libc) pthread_cond_wait(). In particular, the models reflect the behavior of these functions in releasing a lock and subsequently reacquiring the same lock.

Creating New Models

If you are authoring a model for a function that acquires or releases a lock, it is usually best to have the model call the already-modeled function that is most similar. This will ensure that CodeSonar correctly treats the function as acquiring (releasing) a lock, and includes it in the appropriate checks.

If no existing model is appropriate, write your model using the extension functions provided.

The full set of lock-related extension functions is shown below. See the function documentation for annotated examples, usage requirements, and notes on modeling functions with failure cases.

Resolving Lock Operation Identification Problems

If lock acquisition and release functions used in your code have not been identified to CodeSonar with a suitable model or a LOCK_FUNCTIONS or UNLOCK_FUNCTIONS rule, the analysis will likely have both false positives and false negatives for lock-related warnings.

If you have a lock-related warning that you believe is a false positive because lock-acquiring functions have been incorrectly identified, the following cases describe how to identify and resolve the underlying issue. The steps for incorrectly identified lock-release functions are the same, except that the configuration file parameter involved will be UNLOCK_FUNCTIONS and the functions, wrappers and models involved will all relate to releasing locks.

myfunc(a,...) is being treated as if it acquires lock a, but it isn't a lock-acquiring function.

Find the LOCK_FUNCTIONS configuration file rule that matches myfunc() and modify or delete it.

myfunc(a,...) acquires lock a, but CodeSonar doesn't seem to understand that.

There are several possibilities.

Lock acquisition failure [Data Race only]: CodeSonar recognizes myfunc() as a lock-acquiring function that can fail, and the warning is associated with a failure case. In this situation the call to myfunc() will have an associated event explicitly noting that it fails to acquire the lock in the scenario being considered.
- If you would prefer the analysis to behave as if modeled lock-acquiring functions can never fail, set MUTEX_FAILURE_BEHAVIOR=DOESNT_FAIL in your configuration file.
myfunc() is actually a wrapper around a lock-acquiring function lockfunc(). In this situation issues will be reported with respect to lockfunc() (but only if it is itself recognized).
- Set LOCK_FUNCTIONS += ^myfunc()$ in your configuration file. Note: This requires that the first argument to myfunc() is a pointer to the lock. If not, you will need to write a library model.
- If lockfunc() is not recognized as a lock-acquiring function by CodeSonar, we recommend writing a library model. This ensures that it will be correctly handled when used without a wrapper, and improves the analysis for warning classes like Data Race.
myfunc() is a lock-acquiring function that CodeSonar does not recognize.
- Write a library model for myfunc().