PDStack Middleware Library
PDStack middleware library

The PDStack middleware implements state machines defined in the Universal Serial Bus Type-C Cable and Connector Specification and the Universal Serial Bus Power Delivery Specification. The middleware provides a set of Device Policy Manager (DPM) APIs through which the application can initialize, monitor, and configure the middleware operation.

The PDStack middleware operates on top of the USB PD driver included in the MTB PDL CAT2 (mtb-pdl-cat2) peripheral driver library (PDL).

Features:

  1. Supports Type-C port configuration and connection detection in the Sink, source, and dual-role.
  2. Supports Extended Power Range (EPR) in source and sink roles.
  3. Support USB PD communication with the following features:
    • USB PD revision 3.1 compliance
    • USB PD revision 2.0 compliance (backward compatibility)
    • Power contract negotiation in sink and source roles
    • Ability to respond to SOP and SOP' messages to support designs with a captive USB-C cable.
  4. Supports configuration of the port roles and responses through the EZ-PD(TM) Configurator.
  5. Support DPM APIs to initialize, configure, monitor, and control the port operation and send/receive USB PD messages associated with alternate mode discovery, authentication, firmware update, etc.

General description

Include cy_pdstack_common.h, cy_pdstack_dpm.h to get access to all functions and other declarations in this library. See the Quick start guide to start using the PDStack.

See the Supported software and tools section for compatibility information.

See the Changelog section for change history.

PDStack operates on top of the USB PD driver. The USB PD driver has some prerequisites for proper operation. See the "USB PD (USB Power Delivery)" section of the MTB PDL CAT2 (mtb-pdl-cat2) peripheral driver library API reference manual. In addition, see the Limitations and restrictions section for the different PDStack middleware restrictions and limitations.

The PDStack middleware is released in the form of pre-compiled libraries. The following library variants with a different feature set to help limit the memory footprint of the stack in applications are released.

  1. pmg1_pd3_snk_lite - Support USB Type-C sink operation and USB PD Revision 3.1 messaging.
  2. pmg1_pd2_snk_lite - Supports USB Type-C sink operation and USB PD Revision 2.0 messaging. Using this library reduces the flash (code) memory usage by the application.
  3. pmg1_pd3_drp - Supports USB Type-C dual-role operation and USB PD Revision 3.1 messaging. This library can be used in any Power Delivery application.
  4. pmg1_pd3_snk_epr - Supports USB Type-C sink Extended Power Range (EPR). This library can be used in applications that require EPR.
  5. pmg1_pd3_drp_epr - Supports USB Type-C dual role EPR operation and USB PD Revision 3.1 messaging.
  6. pmg1_pd3_drp_epr_cfg - Supports USB Type-C dual role EPR operation, USB PD Revision 3.1 messaging and configurability of stack parameters through the EZ-PD™ Configuration Utility.
  7. wlc1_pd3_snk - Library with support for USB Type-C sink operation and USB PD Revision 3.1 messaging. This library can be used in any Power Delivery WLC1 application.

Quick start guide

PDStack middleware can be used in various development environments such as ModusToolbo(TM)), MBED, etc. See the Supported software and tools section.

These steps describe the simplest way of enabling the PDStack middleware in the application.

  1. Open/create an application where to add the PDStack function.
  2. Add the PDStack middleware to your project. This quick start guide assumes that the environment is configured to use the MTB CAT2 peripheral driver library (PDL) for development and the PDL is included in the project. If you are using the ModusToolbox(TM) development environment, select the application in the Project Explorer window and select the PDStack Middleware in the Library Manager.
  3. Include cy_pdstack_common.h and cy_pdstack_dpm.h to get access to all functions and other declarations in this library.
    #include "cy_pdstack_common.h"
    #include "cy_pdstack_dpm.h"
  4. Define the following data structures required by the PDStack middleware:
    • USB-C port configuration
      /*******************************************************************************
      * PD Port Configuration Structure Initialization
      *******************************************************************************/
      static const uint8_t mtb_usbpd_port0_ext_src_cap[] = {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}; /* SCEDB Configuration */
      static const uint8_t mtb_usbpd_port0_ext_snk_cap[] = {0xB4,0x04,0x01,0xF5,0x00,0x00,0x00,0x00,0x01,0x01,0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x0A,0x05,0x05,0x14,0x00,0x00,0x00}; /* SKEDB Configuration */
      static const uint8_t mtb_usbpd_port0_mfg_name[] = {"Infineon"}; /* Manufacturer Name */
      const cy_stc_pdstack_port_cfg_t mtb_usbpd_port0_pdstack_config =
      {
      .signature = 0x50445343, /* PDSC */
      .version = 0x0100, /* Configuration table version */
      .mfgLenInfo = 0x0D, /* Length of Manufacturer Information */
      .mfgVid = 0x04B4, /* Manufacturer Vendor ID */
      .mfgPid = 0xF501, /* Manufacturer Product ID */
      .mfgName = &mtb_usbpd_port0_mfg_name[0], /* Manufacturer Name */
      .scedbEn = 0, /* SCEDB enable */
      .skedbEn = 1, /* SKEDB enable */
      .extSrcCap = &mtb_usbpd_port0_ext_src_cap[0], /* SCEDB Configuration */
      .extSrcCapSize = 25, /* Size of extSrcCap in bytes */
      .extSnkCap = &mtb_usbpd_port0_ext_snk_cap[0], /* SKEDB Configuration */
      .extSnkCapSize = 24, /* Size of extSnkCap in bytes */
      .portRole = 0, /* Port role */
      .defPortRole = 0, /* Default port role */
      .curLevel = 2, /* Current level */
      .cableDiscCount = 0x14, /* Cable Discover count */
      .srcPdoFlags = {0x00,0x00}, /* Source PDO flags */
      .snkPdoFlags = {0x00,0x00}, /* Sink PDO flags */
      .drpToggleEn = 0, /* DRP toggle enable */
      .rpSupported = 0, /* Rp supported */
      .pdOpEn = 1, /* PD operation enable */
      .prefPwrRole = 0, /* Preferred Power role */
      .portDis = 0, /* Port disable */
      .cableDiscEn = 0, /* Cable Discovery Enable */
      .deadBatSupp = 1, /* Dead battery support */
      .errorRecoveryEn = 1, /* Error recovery enable */
      .accessoryEn = 1, /* Accessory mode enable */
      .rpDetachEn = 1, /* Rp detach enable */
      .vconnRetain = 0, /* VCONN retain */
      .frsConfig = 0, /* FRS configuration */
      .srcPdoCount = 0x00, /* Source PDO count */
      .defSrcPdoMask = 0x00, /* Default Source PDO mask */
      .snkPdoCount = 0x02, /* Sink PDO count */
      .defSnkPdoMask = 0x03, /* Default Sink PDO mask */
      .srcPdo = {}, /* Source PDO */
      .snkPdo = {0x0001905A,0x9A42305A}, /* Sink PDO */
      .snkPdoMinMaxCur = {0x005A,0x005A}, /* Sink PDO min/max current */
      .pdRevision = 0x00000002, /* PD Revision */
      };
    • Device Policy Manager parameters
      const cy_stc_pdstack_dpm_params_t pdstack_port0_dpm_params =
      {
      .dpmRpAudioAcc = CY_PD_RP_TERM_RP_CUR_DEF,
      .dpmDefCableCap = 300,
      .muxEnableDelayPeriod = 0,
      .typeCSnkWaitCapPeriod = 0,
      .defCur = 90
      };
    • Register application callback functions
      /*
      * Application callback functions for the DPM.
      */
      const cy_stc_pdstack_app_cbk_t appCallback =
      {
      app_event_handler,
      #if (!CY_PD_SINK_ONLY)
      psrc_set_voltage,
      psrc_set_current,
      psrc_enable,
      psrc_disable,
      #endif /* (!CY_PD_SINK_ONLY) */
      vconn_enable,
      vconn_disable,
      vconn_is_present,
      vbus_is_present,
      vbus_discharge_on,
      vbus_discharge_off,
      #if (!CY_PD_SOURCE_ONLY)
      psnk_set_voltage,
      psnk_set_current,
      psnk_enable,
      psnk_disable,
      eval_src_cap,
      #endif /* (!CY_PD_SOURCE_ONLY) */
      #if (!CY_PD_SINK_ONLY)
      eval_rdo,
      #endif /* (!CY_PD_SINK_ONLY) */
      eval_dr_swap,
      eval_pr_swap,
      eval_vconn_swap,
      eval_vdm,
      #if ((!(CY_PD_SOURCE_ONLY)) && (!CY_PD_SINK_ONLY))
      eval_fr_swap,
      #endif /* ((!(CY_PD_SOURCE_ONLY)) && (!CY_PD_SINK_ONLY)) */
      vbus_get_value,
      #if (!CY_PD_SINK_ONLY)
      psrc_get_voltage,
      send_src_info
      #endif /* (!CY_PD_SINK_ONLY) */
      };
      The PDStack library uses this set of callbacks registered by the application to perform board-specific tasks such as turning the consumer power path ON/OFF, identifying the optimal source power profile to be used for charging, etc. The library also provides notification of various connections and PD policy state changes, therefore, the rest of the system can be configured as required.
  5. Initialize the PDStack middleware after the start.
    Cy_PdStack_Dpm_Init (&pdStackContext,
    &usbPdContext,
    &mtb_usbpd_port0_pdstack_config,
    (cy_stc_pdstack_app_cbk_t *)&appCallback,
    &pdstack_port0_dpm_params,
    &timerContext);
  6. Start the DPM operation.
    Cy_PdStack_Dpm_Start(&pdStackContext);
    Initializes the USB PD block to detect Type-C connection state changes and USB PD messages and notify the application through callback functions.
  7. Invoke the Cy_PdStack_Dpm_Task function from the main processing loop of the application to handle the device policy tasks for each PD Port.
    Cy_PdStack_Dpm_Task(&pdStackContext);

Configuration considerations

This section consists of instructions on how to configure, and use the PDStack middleware in a design.

  1. After selecting the PDStack middleware through the library manager, the user can select the library variant by editing the code example Makefile:
    • Add 'PMG1_PD3_SNK_LITE' to the COMPONENTS for using the pmg1_pd3_snk_lite library
    • Add 'PMG1_PD2_SNK_LITE' to the COMPONENTS for using the pmg1_pd2_snk_lite library
    • Add 'PMG1_PD3_DRP' to the COMPONENTS for using the pmg1_pd3_drp library
    • Add 'PMG1_PD3_SNK_EPR' to the COMPONENTS for using the pmg1_pd3_snk_epr library
    • Add 'PMG1_PD3_DRP_EPR' to the COMPONENTS for using the pmg1_pd3_drp_epr library
    • Add 'PMG1_PD3_DRP_EPR_CFG' to the COMPONENTS for using the pmg1_pd3_drp_epr_cfg library
    • Add 'WLC1_PD3_SNK' to the COMPONENTS for using the wlc1_pd3_snk library
  2. Configure the USB-C port properties
    • The USB-C port properties are controlled with the cy_stc_pdstack_port_cfg_t structure defined in config_table.h or cy_pdstack_port_config.h file. Please see its description to learn about the parameters and values.
    • Use the EZ-PD(TM) Configurator to configure the properties of the USB-C port including the port role and the default response to various USB PD messages. See Step 4 of the Quick start guide guide for the reference configuration data.
    • For designs supporting EZ-PD(TM) Configuration Utility, configure the properties of the USB-C port dynamically through the selection of appropriate values in the configuration utility tool. See the Limitations and restrictions for the existing restrictions.

Limitations and restrictions

Supported software and tools

This version of the PDStack middleware is validated for compatibility with the following software and tools:

Software and tools Version
ModusToolbox(TM) software 3.1
mtb-pdl-cat2 2.8.0
GCC compiler 10.3.1
IAR compiler 8.42.2
Arm(R) compiler 6 6.13

Changelog

VersionChangesReason for change
3.20.1 Corrected page header of API reference manual. Defect fix.
3.20 Updated to USB PD Revision 3.1 Version 1.8. Feature addition.
Added a new library variant 'pmg1_pd3_drp_epr_cfg' that supports configurability of stack parameters through the EZ-PD™ Configuration Utility. Feature addition.
PdStack has been updated to send Hard Reset if the PDO value in the EPR Request does not match the value of the PDO sent in the EPR_Source_Capabilities. Defect fixes
3.10 Updated to USB PD Revision 3.1 Version 1.7. Feature addition.
Added EPR AVS feature support in the EPR sink library. Feature Addition.
Updated the handling of Get Source Info message for DRP. Defect fixes.
3.0 Added EZ-PD(TM) PMG1 DRP EPR library compliant to USB PD Revision 3.1. New Library
Moved software timer and utility functionality to separate PDUtils middleware library. Feature addition
Updated PDStack to use 27 ms and 29 ms for the tSenderResponse timer while in PD 2.0 and PD3.x contracts respectively. Added API to update the tSenderResponse value from the application space. PD specification updates.
EPR Keepalive process is incorrectly getting disabled during some pd transactions. This has been corrected. Defect fixes.
2.0 Added WLC1 sink library with support for USB Type-C sink operation and USB PD Revision 3.1 messaging.
Note
This version of the PDStack middleware supports only the wlc1_pd3_snk library and is intended to be used in any Power Delivery WLC1 application.
WLC1 device support
1.20 Added libraries for USB Type-C dual role and sink Extended Power Range (EPR) operation New feature addition
Updated the library to work with RTOS New feature addition
Added APIs for changing source/sink pdo capabilities Feature addition.
1.10 Updated Type-C error recovery period to 250 ms. PD compliance specification updates.
Updated the size of the status extended message to 7 bytes. PD compliance specification updates.
USB PD wakeup interrupt is incorrectly getting disabled as part of the software timer operation. This has been corrected. Defect fixes.
API description updated. Documentation update and clarification.
1.0 Initial version

More information

For more information, see the following documents:

Note
The links to the other software component's documentation (middleware and PDL) point to GitHub for the latest available version of the software. To get documentation of the specified version, download from GitHub, and unzip the component archive. The documentation is available in the docs folder.