PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Enumerations | Functions
System
HAL API Reference » HAL Drivers

## General Description

High level interface for interacting with reset and delays.

# Features

This driver provides three categories of functionality:

- Ability to get the last reset reason.
- Ability to delay for a period of time.
- The ability to disable interrupts during a critical section.

# Quick Start

- mtb_hal_system_critical_section_enter and mtb_hal_system_critical_section_exit are used to enable/disable global interrupts
- mtb_hal_system_delay_ms and mtb_hal_system_delay_us are delay functions used to halt the CPU exectution for a specified period of time
- mtb_hal_system_get_reset_reason gets the cause of latest system reset

# Code Snippets

## Snippet 1: Critical Section

Critical section is a portion in the code where all active interrupts are disabled. This is usually provided in places where the code execution must not be disturbed by an interrupt. An example is a firmware controlled communication protocol where timing of each byte must be maintained and any interrupt might cause loss of data.
mtb_hal_system_critical_section_enter returns the current state of interrupts which denote the active interrupts in the system. This must be passed as argument to mtb_hal_system_critical_section_exit while exiting the critical section.

// Disables all interrupts
uint32_t state = mtb_hal_system_critical_section_enter();
// Application code where interrupts must be disabled
// Re-enable all interrupts that were enabled before
mtb_hal_system_critical_section_exit(state);
mtb_hal_system_critical_section_exit
void mtb_hal_system_critical_section_exit(uint32_t old_state)
Exit a critical section.
mtb_hal_system_critical_section_enter
uint32_t mtb_hal_system_critical_section_enter(void)
Enter a critical section.

## Snippet 2: Reset reason

mtb_hal_system_get_reset_reason must be called at the beginning of the main to determine the reason for reset. The return parameters are present in mtb_hal_reset_reason_t.

if (MTB_HAL_SYSTEM_RESET_WDT == mtb_hal_system_get_reset_reason())
{
// WDT caused system reset
// Application code to perform some action to indicate that WDT caused the interrupt
}
else
{
// Reset reason is not WDT Could be POR or XRES. Specify application code to perform some
// action to indicate WDT was not the reset reaon
}
mtb_hal_system_get_reset_reason
mtb_hal_reset_reason_t mtb_hal_system_get_reset_reason(void)
Gets the cause of the latest reset or resets that occurred in the system.
Definition: mtb_hal_system.c:79
MTB_HAL_SYSTEM_RESET_WDT
@ MTB_HAL_SYSTEM_RESET_WDT
A watchdog timer (WDT) reset has occurred.
Definition: mtb_hal_system.h:102

## API Reference
| SYSTEM HAL Results
| SYSTEM specific return codes.

## Enumerations
enum | mtb_hal_reset_reason_t { MTB_HAL_SYSTEM_RESET_NONE = 0 , MTB_HAL_SYSTEM_RESET_WDT = 1 << 0 , MTB_HAL_SYSTEM_RESET_ACTIVE_FAULT = 1 << 1 , MTB_HAL_SYSTEM_RESET_DEEPSLEEP_FAULT = 1 << 2 , MTB_HAL_SYSTEM_RESET_SOFT = 1 << 3 , MTB_HAL_SYSTEM_RESET_HIB_WAKEUP = 1 << 4 , MTB_HAL_SYSTEM_RESET_WCO_ERR = 1 << 5 , MTB_HAL_SYSTEM_RESET_SYS_CLK_ERR = 1 << 6 , MTB_HAL_SYSTEM_RESET_PROTECTION = 1 << 7 , MTB_HAL_SYSTEM_RESET_WARMBOOT = 1 << 8 }
| Flags enum of possible system reset causes. More...

## Functions
uint32_t | mtb_hal_system_critical_section_enter (void)
| Enter a critical section. More...
void | mtb_hal_system_critical_section_exit (uint32_t old_state)
| Exit a critical section. More...
cy_rslt_t | mtb_hal_system_delay_ms (uint32_t milliseconds)
| Requests that the current operation delays for at least the specified length of time. More...
void | mtb_hal_system_delay_us (uint16_t microseconds)
| Requests that the current operation delay for at least the specified number of micro-seconds. More...
mtb_hal_reset_reason_t | mtb_hal_system_get_reset_reason (void)
| Gets the cause of the latest reset or resets that occurred in the system. More...
cy_rslt_t | mtb_hal_system_reset_device (void)
| Resets the device. More...

## Enumeration Type Documentation

## ◆ mtb_hal_reset_reason_t

enum mtb_hal_reset_reason_t

Flags enum of possible system reset causes.

Enumerator
MTB_HAL_SYSTEM_RESET_NONE | No cause.
MTB_HAL_SYSTEM_RESET_WDT | A watchdog timer (WDT) reset has occurred.
MTB_HAL_SYSTEM_RESET_ACTIVE_FAULT | The fault logging system requested a reset from its Active logic.
MTB_HAL_SYSTEM_RESET_DEEPSLEEP_FAULT | The fault logging system requested a reset from its Deep-Sleep logic.
MTB_HAL_SYSTEM_RESET_SOFT | The CPU requested a system reset through it's SYSRESETREQ.
MTB_HAL_SYSTEM_RESET_HIB_WAKEUP | A reset has occurred due to a a wakeup from hibernate power mode.
MTB_HAL_SYSTEM_RESET_WCO_ERR | A reset has occurred due to a watch-crystal clock error.
MTB_HAL_SYSTEM_RESET_SYS_CLK_ERR | A reset has occurred due to a system clock error.
MTB_HAL_SYSTEM_RESET_PROTECTION | A reset has occurred due to a protection violation.
MTB_HAL_SYSTEM_RESET_WARMBOOT | A reset has occurred due wake up from DSRAM, which is a Warm Boot.

## Function Documentation

## ◆ mtb_hal_system_critical_section_enter()

uint32_t mtb_hal_system_critical_section_enter | ( | void |  | ) |

Enter a critical section.

Disables interrupts and returns a value indicating whether the interrupts were previously enabled.

Returns
  Returns the state before entering the critical section. This value must be provided to mtb_hal_system_critical_section_exit() to properly restore the state

See Snippet 1: Critical Section for code snippet on critical section

## ◆ mtb_hal_system_critical_section_exit()

void mtb_hal_system_critical_section_exit | ( | uint32_t | old_state | ) |

Exit a critical section.

Re-enables the interrupts if they were enabled before mtb_hal_system_critical_section_enter() was called. The argument should be the value returned from mtb_hal_system_critical_section_enter().

Parameters

  [in] | old_state | The state of interrupts from mtb_hal_system_critical_section_enter()

See Snippet 1: Critical Section for code snippet on critical section

## ◆ mtb_hal_system_delay_ms()

cy_rslt_t mtb_hal_system_delay_ms | ( | uint32_t | milliseconds | ) |

Requests that the current operation delays for at least the specified length of time.

If this is running in an RTOS aware environment (COMPONENTS+=RTOS_AWARE) or (DEFINES+=CY_RTOS_AWARE) it will attempt to have the RTOS suspend the current task so others can continue to run. If this is not run under an RTOS it will then defer to the standard system delay which is likely to be a busy loop. If this is part of an application that is build with RTOS awareness, but the delay should not depend on the RTOS for whatever reason, use mtb_hal_system_delay_us() with the appropriate 1000x multiplier to the delay time.

Parameters

  [in] | milliseconds | The number of milliseconds to delay for

Returns
  Returns CY_RSLT_SUCCESS if the delay request was successful, otherwise error

## ◆ mtb_hal_system_delay_us()

void mtb_hal_system_delay_us | ( | uint16_t | microseconds | ) |

Requests that the current operation delay for at least the specified number of micro-seconds.

This will generally keep the processor active in a loop for the specified length of time. If this is running under an RTOS, it will NOT attempt to run any other RTOS tasks, however if the scheduler or a high priority interrupt comes it they can take over anyway.

Note: The delay calculation does not account for interrupt processing. If the use case is sensitive to the timing precision of this delay, consider encapsulating this function within a critical section for protection against additional delay.

Parameters

  [in] | microseconds | The number of micro-seconds to delay for

## ◆ mtb_hal_system_get_reset_reason()

mtb_hal_reset_reason_t mtb_hal_system_get_reset_reason | ( | void |  | ) |

Gets the cause of the latest reset or resets that occurred in the system.

Returns
  Returns an enum of flags with the cause of the last reset(s)

Refer Snippet 2: Reset reason for code snippet on mtb_hal_system_get_reset_reason

## ◆ mtb_hal_system_reset_device()

cy_rslt_t mtb_hal_system_reset_device | ( | void |  | ) |

Resets the device.

The mechanism used to reset the device is implementation-specific and the reset behavior differs between devices.

Returns
  This function does not return if successful. Otherwise an error is returned.