PPU Programmable (PROG) v1 Functions

General Description

Functions
__STATIC_INLINE cy_en_prot_status_t	Cy_Prot_DisablePpuProgStruct (PERI_PPU_PR_Type *base)
	This function disables both the master and slave parts of a protection unit. More...
cy_en_prot_status_t	Cy_Prot_ConfigPpuProgMasterStruct (PERI_PPU_PR_Type *base, const cy_stc_ppu_prog_cfg_t *config)
	Configures a Programmable Peripheral Protection Unit (PPU PROG) master protection struct with its protection attributes. More...
cy_en_prot_status_t	Cy_Prot_ConfigPpuProgSlaveStruct (PERI_PPU_PR_Type *base, const cy_stc_ppu_prog_cfg_t *config)
	Configures a Programmable Peripheral Protection Unit (PPU PROG) slave protection struct with its protection attributes. More...
cy_en_prot_status_t	Cy_Prot_EnablePpuProgMasterStruct (PERI_PPU_PR_Type *base)
	Enables the Master PPU PROG structure. More...
cy_en_prot_status_t	Cy_Prot_DisablePpuProgMasterStruct (PERI_PPU_PR_Type *base)
	Disables the Master PPU PROG structure. More...
cy_en_prot_status_t	Cy_Prot_EnablePpuProgSlaveStruct (PERI_PPU_PR_Type *base)
	Enables the Slave PPU PROG structure. More...
cy_en_prot_status_t	Cy_Prot_DisablePpuProgSlaveStruct (PERI_PPU_PR_Type *base)
	Disables the Slave PPU PROG structure. More...
cy_en_prot_status_t	Cy_Prot_GetPpuProgStruct (PERI_PPU_PR_Type **base, cy_en_prot_req_mode_t reqMode, uint32_t ppuProgIndex)
	Functions returns a pointer of the requested unused Programmable PPU structure. More...

Function Documentation

Cy_Prot_DisablePpuProgStruct()

__STATIC_INLINE cy_en_prot_status_t Cy_Prot_DisablePpuProgStruct

(

PERI_PPU_PR_Type *

base

)

This function disables both the master and slave parts of a protection unit.

Note

This functions has an effect only on devices with PERI IP version 1. Refer to the device datasheet for information about PERI HW IP version.

Parameters

base	The base address for the Programmable PU structure to be disabled.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Master and Slave Programmable PU struct was disabled
CY_PROT_FAILURE	The Master and/or slave Programmable PU struct was not disabled
CY_PROT_INVALID_STATE	Function was called on the unsupported PERI IP version

Function Usage

    
    /* Scenario: The struct of PERI_PPU_PR0 needs to be disabled. Or it
                 needs to be reconfigured and hence must first be disabled. */
    
    if(CY_PROT_SUCCESS != Cy_Prot_DisablePpuProgStruct(PERI_PPU_PR0))
    {
        /* Insert error handling */
    }

Cy_Prot_ConfigPpuProgMasterStruct()

cy_en_prot_status_t Cy_Prot_ConfigPpuProgMasterStruct	(	PERI_PPU_PR_Type *	base,
		const cy_stc_ppu_prog_cfg_t *	config
	)

Configures a Programmable Peripheral Protection Unit (PPU PROG) master protection struct with its protection attributes.

This function configures the master struct governing the corresponding slave struct pair. It is a mechanism to protect the slave PPU PROG struct. Since the memory location of the slave struct is known, the address, regionSize and subregions of the configuration struct are not applicable.

Note that only the user/privileged write permissions are configurable. The read and execute permissions are read-only and cannot be configured.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The register base address of the protection struct being configured.
config	Initialization structure with all the protection attributes.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	PPU PROG master struct was successfully configured.
CY_PROT_FAILURE	The resource is locked.
CY_PROT_BAD_PARAM	An incorrect/invalid parameter was passed.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    /* Scenario: A bus master must not be able to access the PERI_PPU_PR0 master
                 and slave structs unless operating with PC=0, "secure" and
                 "privileged" access settings. The PERI_PPU_PR0 slave struct is 
                 already configured and enabled. */

    cy_stc_ppu_prog_cfg_t progPpuCfg_m = {
        /*.address =*/ 0UL,                         /* Not applicable for master struct */
        /*.regionSize =*/ (cy_en_prot_size_t)0UL,   /* Not applicable for master struct */
        /*.subregions =*/ 0UL,                      /* Not applicable for master struct */
        /*.userPermission =*/ CY_PROT_PERM_R,       /* Read access always available for Master */
        /*.privPermission =*/ CY_PROT_PERM_RW,      /*  Allow read and write privileged mode accesses */
        /*.secure =*/ true,                         /* Only allow "secure" bus masters */
        /*.pcMatch =*/ false,                       /* Perform access evaluation */
        /*.pcMask =*/ (uint16_t)0UL                 /* Only allow PC=0 bus masters */
    };
 
    /* Configure the master struct of PROG PPU #0 */
    if(CY_PROT_SUCCESS != Cy_Prot_ConfigPpuProgMasterStruct(PERI_PPU_PR0, &progPpuCfg_m))
    {
        /* Insert error handling */
    }
    else
    {
        /* Enable the master struct of PROG PPU #0 */
        if(CY_PROT_SUCCESS != Cy_Prot_EnablePpuProgMasterStruct(PERI_PPU_PR0))
        {
            /* Insert error handling */
        }
    }

Cy_Prot_ConfigPpuProgSlaveStruct()

cy_en_prot_status_t Cy_Prot_ConfigPpuProgSlaveStruct	(	PERI_PPU_PR_Type *	base,
		const cy_stc_ppu_prog_cfg_t *	config
	)

Configures a Programmable Peripheral Protection Unit (PPU PROG) slave protection struct with its protection attributes.

This function configures the slave struct of a PPU PROG pair, which can protect any peripheral memory region in a device from invalid bus master accesses.

Note that the user/privileged execute accesses are read-only and are always enabled.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The register base address of the protection structure being configured.
config	Initialization structure with all the protection attributes.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	PPU PROG slave struct was successfully configured.
CY_PROT_FAILURE	The resource is locked.
CY_PROT_BAD_PARAM	An incorrect/invalid parameter was passed.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    /* Scenario: A bus master must not be able to access the GPIO port 0 registers 
                 (0x40320000 ~ 0x4032007F) unless it has the "secure" attribute 
                 and is operating at PC=0 or PC=2. */
    
    cy_stc_ppu_prog_cfg_t progPpuCfg_s = {
        /*.address =*/ (uint32_t *)GPIO_PRT0,       /* Starting address at GPIO port 0 base */
        /*.regionSize =*/ CY_PROT_SIZE_256B,        /* Protect block of 256 Bytes */
        /*.subregions =*/ CY_PROT_SUBREGION_DIS4
                      | CY_PROT_SUBREGION_DIS5
                      | CY_PROT_SUBREGION_DIS6
                      | CY_PROT_SUBREGION_DIS7, /* Disable protection for last 128 (4*256/8) Bytes */
        /*.userPermission =*/ CY_PROT_PERM_RW,      /* Allow Read and Write user mode accesses */
        /*.privPermission =*/ CY_PROT_PERM_RW,      /* Allow Read and Write privileged mode accesses */
        /*.secure =*/ true,                         /* Only allow "secure" bus masters */
        /*.pcMatch =*/ false,                       /* Perform access evaluation */
        /*.pcMask =*/ (uint16_t)CY_PROT_PCMASK2     /* Allow PC=0 and PC=2 accesses */
    };
    
    /* Configure the slave struct of PROG PPU #0 */
    if(CY_PROT_SUCCESS != Cy_Prot_ConfigPpuProgSlaveStruct(PERI_PPU_PR0, &progPpuCfg_s))
    {
        /* Insert error handling */
    }
    else
    {
        /* Enable the slave struct of PROG PPU #0 */
        if(CY_PROT_SUCCESS != Cy_Prot_EnablePpuProgSlaveStruct(PERI_PPU_PR0))
        {
            /* Insert error handling */
        }
    }

Cy_Prot_EnablePpuProgMasterStruct()

cy_en_prot_status_t Cy_Prot_EnablePpuProgMasterStruct

(

PERI_PPU_PR_Type *

base

)

Enables the Master PPU PROG structure.

This is a PPU PROG master struct enable function. The PPU PROG protection settings will take effect after successful completion of this function call.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The base address for the protection unit structure being configured.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Master PU struct was enabled.
CY_PROT_FAILURE	The Master PU struct is disabled and possibly locked.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    /* Scenario: The master struct of PERI_PPU_PR0 is configured to protect its
                 slave struct and needs to be enabled. */
    
    if(CY_PROT_SUCCESS != Cy_Prot_EnablePpuProgMasterStruct(PERI_PPU_PR0))
    {
        /* Insert error handling */
    }

Cy_Prot_DisablePpuProgMasterStruct()

cy_en_prot_status_t Cy_Prot_DisablePpuProgMasterStruct

(

PERI_PPU_PR_Type *

base

)

Disables the Master PPU PROG structure.

This is a PPU PROG master struct disable function. The PPU PROG protection settings will seize to take effect after successful completion of this function call.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The base address for the protection unit structure being configured.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Master PU struct was disabled.
CY_PROT_FAILURE	The Master PU struct is enabled and possibly locked.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    
    /* Scenario: The master struct of PERI_PPU_PR0 needs to be disabled. Or it
                 needs to be reconfigured and hence must first be disabled. */
    
    if(CY_PROT_SUCCESS != Cy_Prot_DisablePpuProgMasterStruct(PERI_PPU_PR0))
    {
        /* Insert error handling */
    }

Cy_Prot_EnablePpuProgSlaveStruct()

cy_en_prot_status_t Cy_Prot_EnablePpuProgSlaveStruct

(

PERI_PPU_PR_Type *

base

)

Enables the Slave PPU PROG structure.

This is a PPU PROG slave struct enable function. The PPU PROG protection settings will take effect after successful completion of this function call.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The base address for the protection unit structure being configured.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Slave PU struct was enabled.
CY_PROT_FAILURE	The Slave PU struct is disabled and possibly locked.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    /* Scenario: The slave struct of PERI_PPU_PR0 is configured to protect a 
                 resource and needs to be enabled. */
    
    if(CY_PROT_SUCCESS != Cy_Prot_EnablePpuProgSlaveStruct(PERI_PPU_PR0))
    {
        /* Insert error handling */
    }

Cy_Prot_DisablePpuProgSlaveStruct()

cy_en_prot_status_t Cy_Prot_DisablePpuProgSlaveStruct

(

PERI_PPU_PR_Type *

base

)

Disables the Slave PPU PROG structure.

This is a PPU PROG slave struct disable function. The PPU PROG protection settings will seize to take effect after successful completion of this function call.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The base address for the protection unit structure being configured.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Slave PU struct was disabled.
CY_PROT_FAILURE	The Slave PU struct is enabled and possibly locked.
CY_PROT_INVALID_STATE	The function was called on the device with an unsupported PERI HW version.

Function Usage

    
    /* Scenario: The slave struct of PERI_PPU_PR0 needs to be disabled. Or it
                 needs to be reconfigured and hence must first be disabled. */
    
    if(CY_PROT_SUCCESS != Cy_Prot_DisablePpuProgSlaveStruct(PERI_PPU_PR0))
    {
        /* Insert error handling */
    }

Cy_Prot_GetPpuProgStruct()

cy_en_prot_status_t Cy_Prot_GetPpuProgStruct	(	PERI_PPU_PR_Type **	base,
		cy_en_prot_req_mode_t	reqMode,
		uint32_t	ppuProgIndex
	)

Functions returns a pointer of the requested unused Programmable PPU structure.

Function searches the Programmable PPU structure until it finds one that both the slave and master sections are disabled. After an available structure is located, function enables the slave structure and enables all attributes, to make sure that a subsequent call will not see this as an available (unused) Programmable PPU.

It is up to the user to implement, if needed, a system in which a semaphore will lock-out all but one CPU from calling this function at once.

Note

This function is applicable for CPUSS ver_1 only.

Parameters

base	The base address for the Programmable PPU structure returned if an unused structure was found. If an empty structure was not found, the returned pointer is NULL.
reqMode	This parameter (request mode) selects how the user wants to select a Programmable PPU structure.

reqMode	Description
CY_PROT_REQMODE_HIGHPRIOR	Return the Programmable PPU structure with the highest priority.
CY_PROT_REQMODE_LOWPRIOR	Return the Programmable PPU structure with the lowest priority.
CY_PROT_REQMODE_INDEX	Return the Programmable PPU structure with the specific index.

Parameters

ppuProgIndex

This is the index of the requested Programmable PPU structure. It is only used if the request mode is reqMode = CY_PROT_REQMODE_INDEX.

Returns

Status of the function call.

Status	Description
CY_PROT_SUCCESS	The Slave PU struct was disabled.
CY_PROT_FAILURE	The Master or Slave Programmable PPU struct is disabled and possibly locked.
CY_PROT_UNAVAILABLE	The requested structure in use or there were no unused structures.
CY_PROT_INVALID_STATE	Function was called on unsupported PERI HW version.

Function Usage

    /* Scenario: Need to find available PERI_PPU structure with highest priority 
    *  and configure it.
    */
    
    
    PERI_PPU_PR_Type *reqStr;
    
    /* Check is required structure is unused */
    if (CY_PROT_SUCCESS != Cy_Prot_GetPpuProgStruct(&reqStr, CY_PROT_REQMODE_HIGHPRIOR, 0U))
    {
       /* Insert error handling */
    }
    else
    {
        cy_stc_ppu_prog_cfg_t progPpuCfg_m =
        {
        /*.address =*/ 0UL,                         /* Not applicable for master struct */
        /*.regionSize =*/ (cy_en_prot_size_t)0UL,   /* Not applicable for master struct */
        /*.subregions =*/ 0UL,                      /* Not applicable for master struct */
        /*.userPermission =*/ CY_PROT_PERM_R,       /* Read access always available for Master */
        /*.privPermission =*/ CY_PROT_PERM_RW,      /*  Allow read and write privileged mode accesses */
        /*.secure =*/ true,                         /* Only allow "secure" bus masters */
        /*.pcMatch =*/ false,                       /* Perform access evaluation */
        /*.pcMask =*/ (uint16_t)0UL                 /* Only allow PC=0 bus masters */
        };
         
        /* Configure the master struct of found PERI PPU struct */
        if(CY_PROT_SUCCESS != Cy_Prot_ConfigPpuProgMasterStruct(reqStr, &progPpuCfg_m))
        {
            /* Insert error handling */
        }
        else
        {
            /* Enable the master struct of PROG PPU */
            if(CY_PROT_SUCCESS != Cy_Prot_EnablePpuProgMasterStruct(reqStr))
            {
                /* Insert error handling */
            }
        }

    }