HPI Library
API Reference
HPIS (HPI Slave)

General Description

The Host Processor Interface (HPI) library implements the HPI transport, protocol, register, and PD message handling.

It allow the host processor or EC to monitor the status of the USB PD ports, change configuration, perform firmware updates, and transparently interact with other USB PD devices connected.

HPI communicates over an I2C interface (supported clock frequencies are 1 MHz, 400 kHz, and 100 kHz) with an interrupt line using a GPIO.

Features:

General description

Include cy_hpi_defines.h, cy_hpi.h to get access to all functions and other declarations in this library. See the Quick start guide to start using the HPI Library.

See the Supported software and tools section for compatibility information.

See the Changelog section for change history.

Quick start guide

HPI middleware is used in ModusToolbox(TM) based development environment. See the Supported software and tools section.

These steps describe the simplest method to enable the HPI interface in a ModusToolbox(TM) based application.

  1. Create or open an application to add HPI functions.
  2. Add the HPI 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.
    Add the PDStack and PDUtils middleware along with the PmgAppCommon middleware libraries if the Type-C and Power Delivery functionality is needed in the application.
  3. Include cy_hpi.h to get access to all functions and other declarations in this library.
    #include "cy_hpi.h"
  4. Define the following data structures required by the HPI middleware:
    • SCB I2C and interrupt GPIO configuration structure.
      /* PD stack context structure for port-0 */
      static cy_stc_pdstack_context_t pdStackPort0Ctx;
      /* PD stack context structure for port-1 */
      static cy_stc_pdstack_context_t pdStackPort1Ctx;
      /* I2C and GPIO hardware configuration structure */
      cy_stc_hpi_hw_config_t hpiHwConfig =
      {
      .scbBase = SCB4,
      .scbPort = GPIO_PRT5,
      .slaveAddr = 0x08,
      .ecIntPort = GPIO_PRT3,
      .ecIntPin = 2
      };
    • HPI slave context parameters
      static cy_stc_hpi_context_t hpiContext;
    • Register application callback functions
      static cy_stc_hpi_app_cbk_t hpiAppCbk =
      {
      .ec_intr_write = hpi_ec_intr_write,
      .sys_get_custom_info_addr = NULL,
      #if (CY_HPI_PD_ENABLE)
      .hpi_is_event_enabled = NULL,
      .app_disable_pd_port = NULL,
      #if (DFP_ALT_MODE_SUPP || UFP_ALT_MODE_SUPP)
      .alt_mode_get_status = NULL,
      #endif /* (DFP_ALT_MODE_SUPP || UFP_ALT_MODE_SUPP) */
      .app_update_sys_pwr_state = NULL,
      #if (CY_HPI_PD_CMD_ENABLE)
      #if (DFP_ALT_MODE_SUPP) || (UFP_ALT_MODE_SUPP)
      .set_custom_svid = NULL,
      .set_alt_mode_mask = NULL,
      .app_vdm_layer_reset = NULL,
      .eval_app_alt_mode_cmd = NULL,
      .eval_app_alt_hw_cmd = NULL,
      #endif /* ((DFP_ALT_MODE_SUPP) || (UFP_ALT_MODE_SUPP)) */
      .set_custom_host_cap_control = NULL,
      .app_set_custom_pid = NULL,
      .i2cm_gen_i2c_tunnel_cmd = NULL,
      .switch_vddd_supply = NULL,
      #if (CY_HPI_VDM_QUERY_SUPPORTED)
      .vdm_get_disc_id_resp = NULL,
      .vdm_get_disc_svid_resp = NULL,
      #endif /* (CY_HPI_VDM_QUERY_SUPPORTED) */
      .app_update_bc_src_support = NULL,
      #if (CY_HPI_VBUS_C_CTRL_ENABLE)
      .psnk_set_vbus_cfet_on_ctrl = NULL,
      #endif /* (CY_HPI_VBUS_C_CTRL_ENABLE) */
      .hpi_vconn_enable = NULL,
      .hpi_vconn_disable = NULL,
      #if (CY_HPI_RW_PD_RESP_MSG_DATA)
      .hpi_rw_pd_resp_data = NULL,
      #endif /* (CY_HPI_RW_PD_RESP_MSG_DATA) */
      #endif /* (CY_HPI_PD_CMD_ENABLE) */
      .vbus_get_live_current = vbus_get_live_current,
      #endif /* (CY_HPI_PD_ENABLE) */
      .set_bootloader_run_type = set_bootloader_run_type,
      #if (!CY_HPI_BOOT_ENABLE)
      .hpi_boot_validate_fw = hpi_boot_validate_fw,
      #endif /* (!CY_HPI_BOOT_ENABLE) */
      .hpi_boot_validate_fw_cmd = hpi_boot_validate_fw_cmd,
      #if (!CY_HPI_BOOT_ENABLE)
      .hpi_sys_get_device_mode = hpi_sys_get_device_mode,
      #endif /* (!CY_HPI_BOOT_ENABLE)) */
      #if (CY_HPI_FLASH_RW_ENABLE)
      .hpi_flash_row_write = hpi_flash_row_write,
      .hpi_flash_row_read = hpi_flash_row_read,
      .hpi_flash_access_get_status = NULL,
      .hpi_flash_enter_mode = hpi_flash_enter_mode,
      #endif /* (CY_HPI_FLASH_RW_ENABLE) */
      #if (CCG_UCSI_ENABLE)
      .ucsi_notify = NULL,
      .ucsi_reg_space_write_handler = NULL,
      .ucsi_handle_hpi_commands = NULL,
      .hpi_update_ucsi_reg_space = NULL,
      #endif /* (CCG_UCSI_ENABLE) */
      .hpi_dev_wr_handler_ext = NULL,
      .hpi_port_wr_handler_ext = NULL,
      };
      The HPI library uses these callbacks registered by the application to perform the application-specific tasks such as flash read/write, interrupt GPIO control, VBus control, validate firmware image, and so on.
  5. Invoke the Cy_Hpi_PdEventHandler function from the solution event handler.
    Cy_Hpi_PdEventHandler(&hpiContext, 0, APP_EVT_CONNECT, NULL);
  6. Invoke the Cy_Hpi_I2cInterruptHandler function from the SCB I2C interrupt service function.
    Cy_Hpi_I2cInterruptHandler(&hpiContext);
  7. Initialize the HPI middleware. Configure and initialize the I2C SCB in slave mode, before calling this function.
    Cy_Hpi_Init(&hpiContext, /* Pointer to HPI slave context */
    &hpiHwConfig, /* HPI hardware interface detail */
    &hpiAppCbk, /* Application callbacks */
    &pdStackPort0Ctx, /* Pointer to the Port-0 PdStack context */
    &pdStackPort1Ctx, /* Pointer to the Port-1 PdStack context */
    2 /* Number of Type-C ports supported */
    );
  8. Initialize common features such as HPI version, application versions, flash locations, and device mode based on the application design and current status.
    /* Set HPI version register info. */
    Cy_Hpi_SetHpiVersion (&hpiContext, /* Pointer to HPI slave context */
    0x12345678); /* HPI version register bit value */
    /* Set HPI extended version register info. */
    Cy_Hpi_SetHpiVersionExt(&hpiContext, /* Pointer to HPI slave context */
    0x12345678); /* HPI extended version register bit value */
    /* Set HPI mode register info. */
    Cy_Hpi_SetModeRegs(&hpiContext, /* Pointer to HPI slave context */
    0x00,
    0x00);
    /* Set Bootloader and Application version information. */
    Cy_Hpi_UpdateVersions(&hpiContext, /* Pointer to HPI slave context */
    (uint8_t *)0x000000E0, /* Bootloader FW version offset address */
    (uint8_t *)0x001000E0, /* App-1 FW version offset address */
    (uint8_t *)0x002000E0 /* App-2 FW version offset address */
    );
    /* Set firmware location flash row number. */
    Cy_Hpi_UpdateFwLocations(&hpiContext, /* Pointer to HPI slave context */
    (uint16_t)0x0100, /* App-1 start location flash row number */
    (uint16_t)0x0200); /* App-2 start location flash row number */
  9. Call Cy_Hpi_Task from the main processing loop of the application to handle the command and data received from the HPI master device.
    Cy_Hpi_Task(&hpiContext);

Configuration considerations

Limitations and restrictions

API Reference

 Macros
 This section describes the HPI macros.
 
 Functions
 This section describes the HPI function prototypes.
 
 Data structures
 This section describes the data structures defined by the HPI.
 
 Enumerated types
 This section describes the enumeration types defined by the HPI.