Critical Section and Mutex functions
The functions are listed below.
Function page
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 to
NULLif 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