<< Previous | Next >>

OSMutexCreate

OS_EVENT *OSMutexCreate( INT8U prio, INT8U * err );

Description

This function creates a mutual exclusion semaphore. Note that:

• The LEAST significant 8 bits of the OSEventCnt field of the mutex's event control block are used to hold the priority number of the task owning the mutex or 0xFF if no task owns the mutex.

• The MOST significant 8 bits of the OSEventCnt field of the mutex's event control block are used to hold the priority number to use to reduce priority inversion.

Parameters

prio

The priority to use when accessing the mutual exclusion semaphore. In other words, when the semaphore is acquired and a higher priority task attempts to obtain the semaphore then the priority of the task owning the semaphore is raised to this priority. It is assumed that you will specify a priority that is LOWER in value than ANY of the tasks competing for the mutex.

err

Pointer to error code that will be returned to your application:

• OS_NO_ERR - if the call was successful.

• OS_ERR_CREATE_ISR - you attempted to create a mutex from an ISR

• OS_PRIO_EXIST - a task at the priority inheritance priority already exist.

• OS_ERR_PEVENT_NULL - no more event control blocks available.

• OS_PRIO_INVALID - if the priority you specify is higher that the maximum allowed (i.e. > OS_LOWEST_PRIO)

Return value

!= (void *)0

Pointer to the event control clock (OS_EVENT) associated with the created mutex.

== (void *)0

Error detected.

Library

OS_MUTEX.C