PDL SRF (PDL Secure Request Framework)

General Description

This file contains the cy_pdl_srf_module_register API.

This must be called on the secure side during startup after Secure Request Framework (SRF) initialization in order to call Secure Aware PDL APIs.

Secure Aware PDL

Some APIs are marked as Secure Aware. This means that if the driver's hardware resource is marked as a secure resource in the Peripheral Protection Controller (PPC) and these APIs are called from a non-secure CPU state, the PDL will submit a request to the Secure Request Framework (SRF) middleware to transition to a secure CPU state to perform the operation. From the application's perspective, the API will behave the same whether it is called from a secure or non-secure CPU state albeit slower.

Note that the inverse is not supported - calling to an API that operates on a non-secured resource from a secure CPU state will not be automatically handled and will result in a PPC fault. To perform this action legally, abide by ARM guidelines for calling to NS from S.

The general rule is

1. Secure-aware APIs: Some of these APIs involve multiple PPC regions. See the documentation for individual APIs for restrictions on how these PPC regions must be configured relative to each other. Custom PPC configurations which do not meet the requirements of a security API may be handled as follows:
   1. Access to secure resources from a non-secure processing environment can be enabled by creating a custom secure operation. See the secure request framework documentation for details.
   2. Access to a non-secure resource from a secure processing environment may be achieved either by following ARM's "guidelines for calling to NS from S" or by using the GET_NSALIAS_ADDRESS macro.
2. Non Secure-aware APIs: All involved PPC regions should be either secure (calling to the API in secure CPU state) or non-secure (calling to the API in non-secure CPU state).

This functionality is automatically enabled on devices with ARM TrustZone processors. To disable all driver Secure Awareness, set the DEFINE+=CY_PDL_ENABLE_SECURE_AWARE=0 in the application Makefile. To disable specific drivers, each has a matching macro that can be used in the same way, e.g. RTC has CY_PDL_ENABLE_SECURE_AWARE_RTC. See individual driver documentation for specific macro names.

Marking a hardware resource as Non-Secure via the PPC in the device configurator will also disable the Secure Aware driver to save memory during secure image compilation. For drivers with multiple hardware resource instances (e.g. SCBs), the Secure Aware APIs will take the default or SRF route depending on if the instance they're invoked on is Secured. If all resources are marked Non-Secure, the Secure Aware driver will be disabled.

Secure Awareness is only relevent on APIs which interact with hardware resources. APIs which do not interact with hardware resources have notes in the API's function header comments documenting that they are safe to call from either state.

Setup

The Secure Aware PDL that requires a shared request pool (see SRF documentation) is setup for it to allocate requests from. This pool is initialized by default as part of cybsp_init on the Non-Secure CPU.

The cy_pdl_srf_module_register API must be called with the default cybsp_secure_context secure context to register the secure operations for SRF to reference. This is similarly done as part of cybsp_init, but on the Secure CPU.

API Reference
	PDL SRF Common (PDL Secure Request Framework Common)
	Internal helpers for common code between the Secure Aware PDL drivers.
	RTC SRF (RTC Secure Request Framework)
	Internal operation declarations to enable Secure Aware RTC.
	SMIF SRF (SMIF Secure Request Framework)
	Internal operation declarations to enable Secure Aware SMIF.
	SYSCLK SRF (SYSCLK Secure Request Framework)
	Internal operation declarations to enable Secure Aware SYSCLK.
	SYSPM SRF (SYSPM Secure Request Framework)
	Internal operation declarations to enable Secure Aware SYSPM.
	Macros
	Enums
	Functions