cy_hpi_master.h

/*******************************************************************************
* File Name: cy_hpi_master.h
* \version 1.1.0
*
* Defines APIs for HPI master middleware.
*
********************************************************************************
* \copyright
* (c) 2024, Cypress Semiconductor Corporation (an Infineon company) or
* an affiliate of Cypress Semiconductor Corporation. All rights reserved.
* You may use this file only in accordance with the license, terms, conditions,
* disclaimers, and limitations in the end user license agreement accompanying
* the software package with which this file was provided.
*******************************************************************************/

#ifndef CY_HPI_MASTER_H
#define CY_HPI_MASTER_H

#include <stdint.h>
#include "cy_hpi_master_defines.h"

/**
********************************************************************************
* \addtogroup group_hpi_master
* \{
*
* The Host Processor Interface (HPI) master library implements a set of APIs 
* through which the application communicates over the HPI interface to monitor 
* or control the operating condition of other HPI slave devices. The middleware 
* implements an asynchronous interrupt-based event queue handling.
*
* HPI master communicates over an I2C interface (supported clock frequencies are
* 1 MHz, 400 kHz, and 100 kHz) with an interrupt line using a GPIO.
*
* <b>Features:</b>
* * Firmware version identification
* * Firmware update capability
* * Enquiry of Type-C and USB PD connection status
* * Control of USB PD power profiles
*
********************************************************************************
* \section section_hpim_general_description General description
********************************************************************************
*
* Includes cy_hpi_master_defines.h and cy_hpi_master.h to
* access all the functions and other declarations in this library. See the
* \ref section_hpim_quick_start to use the HPI library.
*
* See the \ref section_toolchain section for compatibility
* information.
*
* See the \ref section_changelog section for change history.
*
********************************************************************************
* \section section_hpim_quick_start Quick Start Guide
********************************************************************************
*
* HPI master middleware is used in ModusToolbox(TM) based development 
* environment. See the \ref section_toolchain section.
*
* These steps describe the simplest method to enable the HPI master 
* middleware in an application.
*
* 1. Create or open an application to add HPI master functions.
* 
* 2. Add the HPI master 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.
*
* 3. Include cy_hpi_master.h and cy_hpi_master_defines.h to get access to all 
* functions and other declarations in this library.
* \snippet snippet/hpim_sut.c snippet_configuration_hpim_include
*
* 4. Define the following data structures required by the HPI master middleware:
*    * HPI master required buffers and data structures
*    \snippet snippet/hpim_sut.c snippet_configuration_hpim_data
*    * HPI master context parameters
*    \snippet snippet/hpim_sut.c snippet_configuration_hpim_context
*    * Register application callback functions
*    \snippet snippet/hpim_sut.c snippet_configuration_hpim_app_cbk
*   The HPI master library uses these callbacks registered by the application
*   to perform the application-specific tasks such as read/write on the I2C bus, handle
*   slave events, handle error conditions, and so on.
* 
* 5. Initialize the HPI master middleware. Configure and initialize the 
*    I2C SCB before calling this function.
*   \snippet snippet/hpim_sut.c snippet_configuration_hpim_init
*
* 6. Register a slave device. The interrupt GPIO is already configured.
*    
*   \snippet snippet/hpim_sut.c snippet_configuration_hpim_slave_init
* 
* 7. Invoke the \ref Cy_HPI_Master_InterruptHandler function from the GPIO interrupt
*    service routine for each slave device.
*   \snippet snippet/hpim_sut.c snippet_configuration_hpim_interrupt
*
* 8. Call \ref Cy_HPI_Master_Task from the main processing loop of the application 
*    to handle the slave device events.
*   \snippet snippet/hpim_sut.c snippet_configuration_hpim_task
*
********************************************************************************
* \section section_hpim_configuration_considerations Configuration considerations
********************************************************************************
*
*
********************************************************************************
* \section section_hpim_miscellaneous Limitations and restrictions
********************************************************************************
*
*
********************************************************************************
*
* \defgroup group_hpim_macros Macros
* \brief
* Describes the HPI master macros.
*
* \defgroup group_hpim_functions Functions
* \brief
* Describes the HPI master function prototypes.
*
* \defgroup group_hpim_data_structures Data Structures
* \brief
* Describes the data structures defined by the HPI master.
*
* \defgroup group_hpim_enums Enumerated types
* \brief
* Describes the enumeration types defined by the HPI master.
*
* \} */

/*******************************************************************************
*                              Type definitions
*******************************************************************************/
/**
* \addtogroup group_hpim_functions
* \{
*/

/*******************************************************************************
    * Function name: Cy_HPI_Master_Init
****************************************************************************//**
*
* Initializes the HPI master context members, application callbacks
* pointer, and initialize the slave devices. Call this function before calling any APIs from this library.
* 
* Initializes the following structure members in the \ref cy_hpi_master_context_t
* before calling this function:
* - ptrEventQueue
* - maxSlaveDevices
* - ptrSlaves
* - ptrScbBase
* - ptrI2cContext
* - respBuffLen
* - ptrRespBuff
*
* \param context
* HPI master library context pointer.
*
* \param appCbk
* Requires application callbacks from the HPI master library.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operations are successful.
* CY_HPI_MASTER_FAILURE - If the operations are not successful.
* CY_HPI_MASTER_INVALID_ARGS - If the input parameter validation failed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_Init(cy_hpi_master_context_t *context,
                                          cy_hpi_master_app_cbk_t *appCbk);


/*******************************************************************************
* Function Name: Cy_HPI_Master_DeInit
****************************************************************************//**
*
* Deinitializes all the global variables and data structure values.
*
* \param context
* HPI master library context pointer.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operations are successful.
* CY_HPI_MASTER_INVALID_ARGS - If the input parameter validation failed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_DeInit(cy_hpi_master_context_t *context);

/*******************************************************************************
* Function Name: Cy_HPI_Master_SlaveDeviceInit
****************************************************************************//**
*
* Configures the HPI slave device information to allow the HPI master to communicate.
* Call this function for each slave device on the same I2C bus.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* HPI slave device I2C address (7 bits).
*
* \param intrGpioPort
* HPI interrupt GPIO port number.
*
* \param intrGpioPin
* HPI interrupt GPIO pin number.
*
* \param portCount
* Number of PD ports supported by the slave device.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operations are successful.
* CY_HPI_MASTER_FAILURE - If the slave registration failed.
* CY_HPI_MASTER_INVALID_ARGS - If the input parameter validation failed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_SlaveDeviceInit(cy_hpi_master_context_t *context,
                                                  uint8_t slaveAddr,
                                                  uint8_t intrGpioPort,
                                                  uint8_t intrGpioPin,
                                                  uint8_t portCount);

/*******************************************************************************
* Function Name: Cy_HPI_Master_InterruptHandler
****************************************************************************//**
*
* Sets the interrupt mask bit and the interrupt is handled by the 
* \ref Cy_HPI_Master_Task function. To get the HPI interrupt pin status, call from the GPIO interrupt routine or periodically from the main loop.
*
* \param context
* HPI master library context pointer.
*
* \param gpioPort
* HPI interrupt GPIO port number.
*
* \param gpioPin
* HPI interrupt GPIO pin number.
*
* \return
* None.
*
*******************************************************************************/
void Cy_HPI_Master_InterruptHandler(cy_hpi_master_context_t *context,
                                    uint8_t gpioPort, 
                                    uint8_t gpioPin);

/*******************************************************************************
* Function name: Cy_HPI_Master_Task
****************************************************************************//**
*
* Handle the events from the slave devices. This function handles the HPI port events
* from the slave in the interrupt context and the associated data
* in queue and is called periodically from the main loop of the application firmware.
*
*
* \param context
* HPI master library context pointer.
*
* \return 
* None.
*
*******************************************************************************/
void Cy_HPI_Master_Task(cy_hpi_master_context_t *context);

/*******************************************************************************
* Function name: Cy_HPI_Master_GetSlaveIndexByAddr
****************************************************************************//**
*
* Function return the index of slave devices for the given slave address.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* I2C address of the slave device.
*
* \return
* Slave device registered index if found.
* \ref CY_HPI_MASTER_UNKNOWN_SLAVE_IDX if not found.
*
*******************************************************************************/
uint8_t Cy_HPI_Master_GetSlaveIndexByAddr(cy_hpi_master_context_t *context,
                                          uint8_t slaveAddr);
    
/******************************************************************************* 
* Function name: Cy_HPI_Master_RegisterRead
****************************************************************************//**
*
* Performs the register read operation using a 16-bit register address.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param regAddress
* HPI register address (16 bits).
*
* \param readBuff
* Reads the data buffer pointer.
*
* \param readLen
* Read the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/    
cy_hpi_master_status_t Cy_HPI_Master_RegisterRead (cy_hpi_master_context_t *context,
                                                  uint8_t slaveAddr,
                                                  uint16_t regAddress,
                                                  uint8_t *readBuff,
                                                  uint16_t readLen);
     
/*******************************************************************************
* Function name: Cy_HPI_Master_RegisterWrite
****************************************************************************//**
*
* Performs the register write operation using a 16-bit register address.
*
* \param context
* Pointer of the HPI master context structure.
*
* \param slaveAddr
* I2C address (7 bits) of the slave device.
*
* \param regAddress
* HPI register address (16 bits).
*
* \param writeBuff
* Writes the data buffer pointer.
*
* \param writeLen
* Write the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/     
cy_hpi_master_status_t Cy_HPI_Master_RegisterWrite(cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 uint16_t regAddress,
                                                 void *writeBuff,
                                                 uint16_t writeLen);
                                                 
/******************************************************************************* 
* Function name: Cy_HPI_Master_DevRegRead
****************************************************************************//**
*
* Reads data from device-specific registers.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param deviceReg
* HPI device-specific register address.
*
* \param readBuff
* Reads the data buffer pointer.
*
* \param readLen
* Read the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_DevRegRead (cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 uint8_t deviceReg,
                                                 uint8_t *readBuff,
                                                 uint16_t readLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_DevRegWrite
****************************************************************************//**
*
* Writes data to the device-specific registers.
*
* \param context
* Pointer of the HPI master context structure.
*
* \param slaveAddr
* I2C address (7 bits) of the slave device.
*
* \param deviceReg
* HPI device-specific register address.
*
* \param writeBuff
* Writes the data buffer pointer.
*
* \param writeLen
*  Write the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_DevRegWrite(cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 uint8_t deviceReg,
                                                 void *writeBuff,
                                                 uint16_t writeLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_FlashMemoryRead
****************************************************************************//**
*
* Reads data from the HPI flash memory region.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param readBuff
* Read the data buffer pointer.
*
* \param readLen
* Read the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_FlashMemoryRead (cy_hpi_master_context_t *context,
                                                     uint8_t slaveAddr,
                                                     uint8_t *readBuff,
                                                     uint16_t readLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_FlashMemoryWrite
****************************************************************************//**
*
* Writes data to the HPI flash memory region.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param writeBuff
* Write the data buffer pointer.
*
* \param writeLen
* Writes the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_FlashMemoryWrite(cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 void *writeBuff,
                                                 uint16_t writeLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_PortRegRead
****************************************************************************//**
*
* Port register reads the API will be used to read all port-specific registers.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param port
* Reads the slave port number associated with the register.
*
* \param portReg
* Port register address.
*
* \param readBuff
* Reads the data buffer pointer.
*
* \param readLen
* Read the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_PortRegRead(cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 uint8_t port,
                                                 uint8_t portReg,
                                                 void *readBuff,
                                                 uint16_t readLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_PortRegWrite
****************************************************************************//**
*
* Port register write API to all the port-specific registers.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param port
* Writes the Slave port number associated with the register.
*
* \param portReg
* Port register address.
*
* \param writeBuff
* Writes the data buffer pointer.
*
* \param writeLen
* Write the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_PortRegWrite(cy_hpi_master_context_t *context,
                                                    uint8_t slaveAddr,
                                                    uint8_t port,
                                                    uint8_t portReg,
                                                    void *writeBuff,
                                                    uint16_t writeLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_PdResponseRegRead
***************************************************************************//**
*
* PD Response register read API is used for response register read operations.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param port
* Slave device port number.
*
* \param offset
* Offset from the response register base address.
*
* \param readData
* Reads the data buffer pointer.
*
* \param readLen
* Read the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_PdResponseRegRead(cy_hpi_master_context_t *context,
                                                 uint8_t slaveAddr,
                                                 uint8_t port,
                                                 uint16_t offset,
                                                 void *readData,
                                                 uint16_t readLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_PdResponseRegWrite
****************************************************************************//**
*
* PD Response register write API is used for response register write operations.
*
* \param context
* HPI master library context pointer.
*
* \param slaveAddr
* Slave device I2C address (7 bits).
*
* \param port
* Slave device port number.
*
* \param offset
* Offset from the response register base address.
*
* \param writeBuff
* Writes the data buffer pointer.
*
* \param writeLen
* Write the number of bytes.
*
* \return
* CY_HPI_MASTER_SUCCESS - If the operation is successful.
* CY_HPI_MASTER_I2C_FAILURE - If the operation failed.
* CY_HPI_MASTER_INVALID_ARGS - Invalid arguments passed.
*
*******************************************************************************/
cy_hpi_master_status_t Cy_HPI_Master_PdResponseRegWrite(cy_hpi_master_context_t *context,
                                                    uint8_t slaveAddr,
                                                    uint8_t port,
                                                    uint16_t offset,
                                                    void *writeBuff,
                                                    uint16_t writeLen);

/*******************************************************************************
* Function name: Cy_HPI_Master_SleepAllowed
****************************************************************************//**
*
* Checks if the device enters into Deep Sleep mode.
*
* \param context
* HPI master library context pointer.
*
* \return
* true - If switches into Deep Sleep mode.
* false - If the operation failed.
*
*******************************************************************************/
bool Cy_HPI_Master_SleepAllowed(cy_hpi_master_context_t *context);

/** \} group_hpim_functions */

#endif  /* CY_HPI_MASTER_H */

/* [END OF FILE] */