 |
MTB CAT5 Peripheral driver library
|
|
MTB CAT5 Peripheral driver library
|
PDL depends on the Core Library. Download it from https://github.com/Infineon/core-lib and add cy_utils.h to the include search path.
Include cy_pdl.h in your source code to use PDL.
To successfully develop software for the CAT5 family of devices, you must configure the peripherals to implement desired behavior. In addition, you must configure clocks, GPIO, and interrupts, as well as route signals from one peripheral to another.
This introduction covers some high level concepts that help you understand and use the PDL to accomplish these tasks. The topics are:
This PDL API Reference covers the peripheral drivers. Documentation on other parts of the overall software development kit are in there respective references, such as the Bootloader SDK API Reference and the BLE API Reference.
PDL is the software development kit for the CAT5 family of devices. Although called the Peripheral Driver Library it contains much more than driver source code.
The PDL occupies the space between application code and the hardware IP blocks (peripherals). It provides driver source code you use to customize drivers for an application. To see the exact list of available drivers, expand the PDL API Reference in the left menu. It also includes all required device-specific header and startup files.
The PDL manages all register access. This reduces the need to understand register usage and bit fields, thus easing software development for the extensive set of peripherals provided for CAT5 devices.
The CAT5 device CYW55500A1 uses a Cortex® M33. The hardware defines a shared register set and memory map for all peripherals.
The set of available peripherals varies per device. In some cases there are multiple instances of the same peripheral; for example, multiple Serial Communication Blocks (SCB). Each peripheral instance may itself operate on multiple instances of user data.
To enable a peripheral to be used by either or both cores, as well as multiple instances of configurable peripherals operating on (potentially) multiple instances of data, the PDL implements a simple, consistent design based on three fundamental concepts.
Base Hardware Address: At the hardware level, peripheral features and behavior are controlled by registers. Each peripheral instance has a base hardware address that points to the registers for that instance. The PDL uses this base address to access the necessary registers. A device-specific header file defines the symbols for the base hardware address of each instance of each peripheral.
Each such file defines a symbol that represents a pointer to the base hardware address for each instance of each peripheral on the device. Use this symbol in your code. The next snippet shows the symbols for instances of the SCB peripheral on this device, which supports nine SCB instances:
The header file contains similar definitions for each peripheral.
Configuration Structure: Each peripheral instance is configurable. Modify values in a PDL configuration structure to change behavior to fit design requirements. The PDL then manages register access using the base hardware address.
Context Structure: A PDL driver may require memory to perform operations. A driver does not allocate memory for this purpose. Firmware allocates the required memory by declaring an instance of a context structure. The address of this variable is passed in function calls. The PDL defines all necessary context structures.
The PDL manages the contents of the context variable. Firmware does not read or write the values of the fields in a context variable. In effect, firmware provides a scratch pad in memory for the PDL driver to do its work. Firmware must ensure that a context variable remains in scope when in use. Typically a context variable is declared as static, or as a global variable.
Many PDL API function calls require a parameter representing one or more of these three concepts. The precise details vary per peripheral, but the design is consistent. There are three commonly-named parameters in the PDL, used to support this design.
| Parameter | Data Type | Purpose |
|---|---|---|
base | <peripheral>_Type* | Base hardware address for an instance of a peripheral |
In addition, all functions follow this naming convention: Cy_<Peripheral>_<FunctionName>().
Firmware must initialize and enable a driver before using it. The PDL API has functions for the purpose. Some peripherals may not implement one or more of these common functions because they aren’t needed for that particular peripheral.
| Name | Purpose | Example |
|---|---|---|
| Cy_<Peripheral>_Init() | Initialize a peripheral, typically based on a config structure | Cy_SCB_UART_Init() |
| Cy_<Peripheral>_DeInit() | de-initialize a peripheral | Cy_SCB_UART_DeInit() |
| Cy_<Peripheral>_Enable() | turn on the peripheral | Cy_SCB_UART_Enable() |
| Cy_<Peripheral>_Disable() | turn off the peripheral | Cy_SCB_UART_Disable() |
Return Status Code: Each driver has a unique return status enumeration type - cy_en_<peripheral>_status_t. The type is used by functions within the driver to indicate the return status. Drivers return success status code with a value of 0. The status code consists of the following fields:
Example of return status type:
A direct effect of the context structure described in the PDL Design section is that the PDL drivers do not dynamically allocate memory. The user allocates the memory required by the driver, by declaring a context structure.
