cy_pra_8h

The header file of the PRA driver. The API is not intended to be used directly by the user application.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Version

2.20

Copyright

Copyright 2020 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_PRA_REG32_CLR_SET(regIndex, field, value)

Provides get-clear-modify-write operations with a name field and value and writes a resulting value to the 32-bit register.

note

An attempt to access not-supported registers (not secure and not listed in the TRM) results in an error. The list of the registers that can be accessed by the PRA driver directly is defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.

Parameters
  • regIndex – The register address index.

  • field – The field to be updated.

  • value – The value to write.

CY_PRA_REG32_SET(regIndex, value)

Writes the 32-bit value to the specified register.

note

An attempt to access not-supported registers (not secure and not listed in the TRM) results in an error. The list of the registers that can be accessed by the PRA driver directly is defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.

Parameters
  • regIndex – The register address index.

  • value – The value to write.

CY_PRA_REG32_GET(regIndex)

Reads the 32-bit value from the specified register.

note

An attempt to access not-supported registers (not secure and not listed in the TRM) results in an error. The list of the registers that can be accessed by the PRA driver directly is defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.

Parameters
  • regIndex – The register address index.

Returns

The read value.

CY_PRA_CM0_WAKEUP()

The request to wake up the Cortex-M0+ core.

CY_PRA_FUNCTION_CALL_RETURN_PARAM(msgType, funcIndex, param)

Calls the specified function with the provided parameter and returns the execution status.

Parameters
  • msgType – The function type.

  • funcIndex – The function reference.

  • param – The pointer to the function parameter.

Returns

The function execution status.

CY_PRA_FUNCTION_CALL_RETURN_VOID(msgType, funcIndex)

Calls the specified function without a parameter and returns void.

Parameters
  • msgType – The function type.

  • funcIndex – The function reference.

Returns

The function execution status.

CY_PRA_FUNCTION_CALL_VOID_PARAM(msgType, funcIndex, param)

Calls the specified function with the provided parameter and returns void.

Parameters
  • msgType – The function type.

  • funcIndex – The function reference.

  • param – The pointer to the function parameter.

CY_PRA_FUNCTION_CALL_VOID_VOID(msgType, funcIndex)

Calls the specified function without a parameter and returns void.

Parameters
  • msgType – The function type.

  • funcIndex – The function reference.

CY_PRA_GET_PIN_PROT_TYPE(base, pinNum)

Compares the PORT and PIN number with secure PIN list and returns PIN protection type.

Parameters
  • base – GPIO Port address

  • pinNum – GPIO PIN number

Returns

The categories of PIN.

CY_PRA_IS_PORT_SECURE(base)

Compares the PORT with secure PIN list and returns PORT protection status.

Parameters
  • base – GPIO Port address

Returns

true if port is secure otherwise false.

CY_PRA_GET_PORT_REG_INDEX(base, subIndex)

Compares the PORT and PIN number with secure PIN list and returns PORT index.

Parameters
  • base – GPIO Port address

  • subIndex – register index of GPIO PORT

Returns

PRA GPIO PORT register index

CY_PRA_GET_HSIOM_REG_INDEX(base, subIndex)

Compares the PORT with secure PIN list and returns HSIOM port index.

Parameters
  • base – GPIO Port address

  • subIndex – register index of HSIOM PORT

Returns

PRA HSIOM PORT register index

Enums

enum cy_en_pra_status_t

cy_en_pra_status_t: Status definitions of the PRA function return values.

Values:

enumerator CY_PRA_STATUS_SUCCESS

Returns success.

enumerator CY_PRA_STATUS_ACCESS_DENIED

Access denied - PRA does not allow a call from Non-Secure.

enumerator CY_PRA_STATUS_INVALID_PARAM

Invalid parameter.

enumerator CY_PRA_STATUS_ERROR_PROCESSING

An error while applying the device configuration.

enumerator CY_PRA_STATUS_REQUEST_SENT

The IPC message status when sent from Non-Secure to Secure.

enumerator CY_PRA_STATUS_ERROR_SYSPM_FAIL

SysPM failure.

enumerator CY_PRA_STATUS_ERROR_SYSPM_TIMEOUT

SysPM operation timeout.

enumerator CY_PRA_STATUS_ERROR_PRA_VERSION

The driver version mismatch between Cortex-M0+ and Cortex-M4.

enumerator CY_PRA_STATUS_INVALID_PARAM_ECO

Returns Error while validating the ECO parameters.

enumerator CY_PRA_STATUS_INVALID_PARAM_EXTCLK

Returns Error while validating the CLK_EXT parameters.

enumerator CY_PRA_STATUS_INVALID_PARAM_ALTHF

Returns Error while validating the CLK_ALTHF parameters.

enumerator CY_PRA_STATUS_INVALID_PARAM_ILO

Returns Error while validating the CLK_ILO parameters.

enumerator CY_PRA_STATUS_INVALID_PARAM_PILO

Returns Error while validating the CLK_PILO parameters.

enumerator CY_PRA_STATUS_INVALID_PARAM_WCO

Returns Error while validating the CLK_WCO parameters.

enumerator CY_PRA_STATUS_INVALID_ECO_PROVISION

Returns Error while validating the provisioned CLK_ECO policy.

enumerator CY_PRA_STATUS_INVALID_EXTCLK_PROVISION

Returns Error while validating the provisioned CLK_EXT policy.

enumerator CY_PRA_STATUS_INVALID_WCO_PROVISION

Returns Error while validating the provisioned CLK_WCO policy.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX0

Returns Error while validating PATH_MUX0.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX1

Returns Error while validating PATH_MUX1.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX2

Returns Error while validating PATH_MUX2.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX3

Returns Error while validating PATH_MUX3.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX4

Returns Error while validating PATH_MUX4.

enumerator CY_PRA_STATUS_INVALID_PARAM_PATHMUX5

Returns Error while validating PATH_MUX5.

enumerator CY_PRA_STATUS_INVALID_PARAM_FLL0

Returns Error while validating FLL.

enumerator CY_PRA_STATUS_INVALID_PARAM_PLL0

Returns Error while validating PLL0.

enumerator CY_PRA_STATUS_INVALID_PARAM_PLL1

Returns Error while validating PLL1.

enumerator CY_PRA_STATUS_INVALID_PARAM_PLL_NUM

Returns Error for the invalid PLL number.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKLF

Returns Error while validating CLK_LF.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF0

Returns Error while validating CLK_HF0.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF1

Returns Error while validating CLK_HF1.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF2

Returns Error while validating CLK_HF2.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF3

Returns Error while validating CLK_HF3.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF4

Returns Error while validating CLK_HF4.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKHF5

Returns Error while validating CLK_HF5.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKPUMP

Returns Error while validating CLK_PUMP.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKBAK

Returns Error while validating CLK_BAK.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKFAST

Returns Error while validating CLK_FAST.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKPERI

Returns Error while validating CLK_PERI.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKSLOW

Returns Error while validating CLK_SLOW.

enumerator CY_PRA_STATUS_INVALID_PARAM_SYSTICK

Returns Error while validating CLK_ALT_SYS_TICK.

enumerator CY_PRA_STATUS_INVALID_PARAM_CLKTIMER

Returns Error while validating CLK_TIMER.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PWR

Returns Error while initializing power.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_ECO

Returns Error while initializing ECO.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_EXTCLK

Returns Error while enabling CLK_EXT.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_ALTHF

Returns Error while enabling CLK_ALTHF.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_ILO

Returns Error while enabling/disabling CLK_ILO.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PILO

Returns Error while enabling/disabling CLK_ALTHF.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_WCO

Returns Error while enabling/disabling CLK_WCO.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_ECO_ENABLED

Returns Error while enabling CLK_ECO.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_ECO_PROVISION

Returns Error if failed to process the provisioned CLK_ECO policy.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_EXTCLK_PROVISION

Returns Error if failed to process the provisioned CLK_EXT policy.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_WCO_PROVISION

Returns Error if failed to process the provisioned CLK_WCO policy.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX0

Returns Error while setting PATH_MUX0.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX1

Returns Error while setting PATH_MUX1.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX2

Returns Error while setting PATH_MUX2.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX3

Returns Error while setting PATH_MUX3.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX4

Returns Error while setting PATH_MUX4.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PATHMUX5

Returns Error while setting PATH_MUX5.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_FLL0

Returns Error while enabling/disabling FLL.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_FLL0_ENABLED

Returns Error while trying to enable an already enabled FLL.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PLL0

Returns Error while enabling/disabling PLL0.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PLL1

Returns Error while enabling/disabling PLL1.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_PLL_ENABLED

Returns Error while trying to enable an already enabled PLL.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKLF

Returns Error while enabling/disabling CLK_LF.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF0

Returns Error while enabling/disabling CLK_HF0.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF1

Returns Error while enabling/disabling CLK_HF1.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF2

Returns Error while enabling/disabling CLK_HF2.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF3

Returns Error while enabling/disabling CLK_HF3.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF4

Returns Error while enabling/disabling CLK_HF4.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKHF5

Returns Error while enabling/disabling CLK_HF5.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKPUMP

Returns Error while enabling/disabling CLK_PUMP.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKBAK

Returns Error while enabling/disabling CLK_BAK.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKFAST

Returns Error while enabling/disabling CLK_FAST.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKPERI

Returns Error while enabling/disabling CLK_PERI.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKSLOW

Returns Error while enabling/disabling CLK_SLOW.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_SYSTICK

Returns Error while enabling/disabling CLK_ALT_SYS_TICK.

enumerator CY_PRA_STATUS_ERROR_PROCESSING_CLKTIMER

Returns Error while enabling/disabling CLK_TIMER.

enum cy_en_pra_pin_prot_type_t

cy_en_pra_pin_prot_type_t: GPIO PIN protection type.

Values:

enumerator CY_PRA_PIN_SECURE

Is a secure PIN.

Can’t be updated from CM4 application through register level PRA policy. This PIN can only be updated through service-level policy

enumerator CY_PRA_PIN_SECURE_UNCONSTRAINED

Is a secure PIN.

Can be updated from CM4 application through register level PRA policy

enumerator CY_PRA_PIN_SECURE_NONE

Not a secure PIN.

Functions

void Cy_PRA_Init(void)

Initializes the PRA driver:

  • Initializes the register access array with the register addresses (Cortex-M0+)

  • Sets up the IPC communication between CPU cores

  • Checks that the driver versions match on the Cortex-M0+ and Cortex-M4 sides.

Call the function before accessing any protected registers. It is called during a device startup from SystemInit().

cy_en_pra_status_t Cy_PRA_SendCmd(uint16_t cmd, uint16_t regIndex, uint32_t clearMask, uint32_t setMask)

Takes the parameters, passes them to the secure Cortex-M0+ via IPC, waits for Cortex-M0+ to finish and reports the status.

Parameters
  • cmd – The command to execute on the secure side. The macros for this parameter are defined in the cy_pra.h file with the CY_PRA_MSG_TYPE_ prefix.

  • regIndex – The index of the function or register depending on the command parameter. The macros for this parameter are defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.

  • clearMask – Data sent to secure the core.

  • setMask – Additional data send to secure the core.

Returns

The command execution status. For the register read command, the read value is returned.

cy_en_pra_pin_prot_type_t Cy_PRA_GetPinProtType(GPIO_PRT_Type *base, uint32_t pinNum)

Find the matching PORT and PIN number from External clock secure PIN list and returns protection status of the PIN.

bool Cy_PRA_IsPortSecure(GPIO_PRT_Type *base)

Find the matching PORT from External clock secure PIN list and returns protection status of the PORT.

uint16_t Cy_PRA_GetPortRegIndex(GPIO_PRT_Type *base, uint16_t subIndex)

Find the matching PORT and PIN number from External clock secure PIN list and returns port address index.

uint16_t Cy_PRA_GetHsiomRegIndex(GPIO_PRT_Type *base, uint16_t subIndex)

Find the matching PORT address from External clock secure PIN list and returns HSIOM port address index.