Critical Section and Mutex Resources

The Critical Section and Mutex functions are concerned with protecting sections of application code from preemption and re-entrancy. These resources are provided in the header file portmacro.h.

• The Critical Section and Mutex functions are described in Section 10.3.1.

• The Critical Section and Mutex structures are described in Section 10.3.2.

Critical Section and Mutex functions

The functions are listed below.

Function page

1. ZPS_eEnterCriticalSection

2. ZPS_eExitCriticalSection

3. ZPS_u8GrabMutexLock

4. ZPS_u8ReleaseMutexLock

Parent topic:Critical Section and Mutex functions

ZPS_eEnterCriticalSection

uint8 ZPS_eEnterCriticalSection(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to mark the end of a critical section of application code. The function ZPS_eEnterCriticalSection() must have been called at the start of the critical section.

This function can be used to mark the start of a critical section of application code - this is a code section that cannot be preempted by an interrupt with priority level less than 12. The function ZPS_eExitCriticalSection() must be called at the end of the critical section.

A pointer to a ‘priority level’ value must be provided, which contains the current priority level of the main application thread (when critical sections are not being executed). When a critical section is entered, the priority level of the main thread is increased such that interrupts with a priority of 11 or less cannot preempt the main thread. At the end of the critical section, the priority level of the main thread is returned to its value from before the critical section was entered.

Optionally, a mutex can also be applied during the critical section to protect the section from re-entrancy. If a mutex is required, a pointer must be provided to a user- defined mutex function with the following prototype:

((bool_t*) (*) (void))

This function must define and maintain a Boolean flag that indicates whether the corresponding mutex is active (TRUE) or inactive (FALSE). This flag is used by ZPS_eEnterCriticalSection() to determine whether the mutex is available.

• If this flag reads as FALSE, the mutex is applied and the above mutex function must set the flag to TRUE.

• If the flag is already TRUE, then the mutex cannot be applied - in this case, ZPS_eEnterCriticalSection() returns a failure.

Critical sections and mutexes are further described in Section 6.9.3.

Parent topic:ZPS_eEnterCriticalSection

Parameters

• hMutex Pointer to user-defined mutex function (see above) - set to NULL if no mutex is required

• psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1)

Parent topic:ZPS_eEnterCriticalSection

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_eEnterCriticalSection

Parent topic:Critical Section and Mutex functions

ZPS_eExitCriticalSection

uint8 ZPS_eExitCriticalSection(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to mark the end of a critical section of application code. The function ZPS_eEnterCriticalSection() should be called at the start of the critical section.

A pointer to the ‘priority level’ value must be provided. If a mutex was used in the critical section, a pointer to the relevant mutex function must be provided in order to release the mutex.

Critical sections and mutexes are further described in Section 6.9.3.

Parent topic:ZPS_eExitCriticalSection

Parameters

• hMutex Pointer to user-defined mutex function (see above) - set toNULL if no mutex was used.

• psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_eExitCriticalSection

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_eExitCriticalSection

Parent topic:Critical Section and Mutex functions

ZPS_u8GrabMutexLock

uint8 ZPS_u8GrabMutexLock(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to apply a mutex at the start of a section of application code that is to be protected from re-entrancy. The function **ZPS_u8ReleaseMutexLock()**must be called at the end of the mutex-protected section to release the mutex.

A pointer must be provided to a user-defined mutex function with the following prototype:

((bool_t*) (*) (void))

This function must define and maintain a Boolean flag which indicates whether the corresponding mutex is active (TRUE) or inactive (FALSE). This flag is used by ZPS_u8GrabMutexLock() to determine whether the mutex is available. If this flag reads as FALSE, the mutex is applied and the above mutex function must set the flag to TRUE, but if the flag is already TRUE then the mutex cannot be applied - in the latter case, ZPS_u8GrabMutexLock() returns a failure.

A pointer to a ‘priority level’ value must be provided, which contains the current priority level of the main application thread (when mutex protection is not being implemented). When a mutex is applied, the priority level of the main thread is increased such that interrupts with a priority of 11 or less cannot preempt the main thread. When the mutex is released, the priority level of the main thread will be returned to its value from before the mutex was applied.

Mutexes are further described in Section 6.9.3.

Parent topic:ZPS_u8GrabMutexLock

Parameters

• hMutex Pointer to user-defined mutex function (see above)

• psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_u8GrabMutexLock

Returns

0x00 for success, 0x01 for failure (all other values are reserved).

Parent topic:ZPS_u8GrabMutexLock

Parent topic:Critical Section and Mutex functions

ZPS_u8ReleaseMutexLock

uint8 ZPS_u8ReleaseMutexLock(
                    void *hMutex,
                    uint32* psIntStore);

Description

This function can be used to release a mutex that has been applied to a section of application code. The function ZPS_u8GrabMutexLock() must have been called at the start of the mutex-protected section.

A pointer to the relevant mutex function must be provided in order to release the mutex. A pointer to the ‘priority level’ value must also be provided.

Mutexes are further described in Section 6.9.3.

Parent topic:ZPS_u8ReleaseMutexLock

Parameters

• hMutex Pointer to user-defined mutex function (see above).

• psIntStore Pointer to structure containing ‘priority level’ value (see Section 10.3.2.1).

Parent topic:ZPS_u8ReleaseMutexLock

Returns

0x00 for success, 0x01 for failure (all other values are reserved)

Parent topic:ZPS_u8ReleaseMutexLock

Parent topic:Critical Section and Mutex functions

Parent topic:Critical Section and Mutex Resources

Critical Section and Mutex Structures

u32MicroIntStorage

u32MicroIntStorageis a 32-bit mask of the interrupts currently enabled. The u32MicroIntStoragestructure is used in critical sections and mutex-protected sections where u32MicroIntStoragetakes the interrupts that have been enabled.

Parent topic:Critical Section and Mutex Structures

Parent topic:Critical Section and Mutex Resources

Parent topic:General ZPS Resources