/*******************************************************************************
 * (c) Copyright 2011 Actel Corporation.  All rights reserved.
 *
 *  This file contains Unified I2C Driver Abstraction Layer function
 *  declarations for different I2C types.
 *  These APIs abstract variations in APIs of different I2Cs in application
 *  development
 *
 * Note - Interrupt service routines and other related functions are not
 *        implemented in these wrappers as they are directly to be registered
 *        with NVIC or CIC handlers.
 *
 * SVN $Revision: 3994 $
 * SVN $Date: 2011-11-18 18:08:46 +0530 (Fri, 18 Nov 2011) $
 */
/*=========================================================================*//**
  @mainpage Unified I2C Driver Abstraction Layer (UI2C DAL)

  @section intro_sec Introduction
  The Unified I2C Driver Abstraction Layer (UI2C DAL) provides a set of APIs.
  These APIs can be used in application software development to access/configure
  different types of I2Cs involved in system design. These APIs can be adapted
  for use as part of an operating system but the implementation of the adaptation
  layer between I2C DAL and the operating system's driver model is outside the
  scope of this driver.

  @section hw_dependencies Hardware Flow Dependencies
  UI2C DAL as is will not directly depend on hardware design flow. Use of
  UI2C DAL depends on choice of application software architect. But when
  used, UI2C DAL requires any one or a combination of below I2C cores.
    - CoreI2C IP core configured in the Libero workbench and same base addresses
      are provided while opening UI2C DAL channel for the same.
    - MSS I2Cs (v.0.2 or above) configured using MSS Configurator tool.
      IO signals of MSS I2Cs shall be routed to external pins using IOMUXes
      in configurator tool.

  Interrupts generated by either soft I2C core or MSS I2Cs are not handled
  in UI2C DAL. For soft I2C cores, interrupts should be handled by CoreInterrupt
  IP and corresponding driver. For hard I2C cores like MSS I2C interrupt
  handlers should be planted in NVIC handler provided by "Cortex Microcontroler
  Software Interface Standard - Peripheral Access Layer" (CMSIS-PAL).

  @section Driver Configuration
  The configuration of all features internal to UI2C DAL is covered by this
  driver with the exception of the user level configuration that depends on the
  system design. While generating UI2C DAL from Firmware Catalog, a GUI is
  displayed. This GUI provides options to enable or disable support for
  different I2C types supported by UI2C DAL. The UI2C DAL cannot be
  generated unless at least one type of I2C is enabled on the configuration
  dialog.

  The configuration GUI generates the ui2c_dal_cfg.h header file that will
  be used in UI2C DAL source code to resolve build time dependencies. You
  need to generate the I2C drivers’ source files into the project that are
  chosen to be enabled in the above configuration window. The latest version
  of CMSIS-PAL and HAL source files should also be included in the project
  when MSS I2C and CoreI2C are used in the project.

  @section theory_op Theory of Operation
  The following steps are involved in the operation of UI2C DAL:
    - Configuration
    - Initialization.
    - Opening a communication channel.
    - Using APIs.

  UI2C DAL operation depends on user configuration at the time of generation.

  Configuration
  The UI2C DAL operation depends on user configuration at the time of generation
  as explained in the driver configuration section.

  Initialization
  After the configuration is completed, the UI2C DAL should be initialized by
  calling the corresponding initialization functions of individual I2C driver's
  intended to use in the system.

  Opening a Communication channel
  Once initialization is completed, a communication channel needs to be opened
  to associate with the I2C type through which communication has to be performed.
  This should be done by calling the corresponding "open" function of that I2C type.
  For example, to open a CoreI2C channel, one should call the
  UI2C_core_I2C_open ( &channel_a, &g_core_i2c). You need to create the instance
  structures for CoreI2C types and provide the same as argument for corresponding
  open functions. You need also create as many channel structures as required to
  assign the I2Cs by calling the open functions. Once the open function is called,
  the corresponding I2C type is associated with the channel.

  Using APIs
  All further UI2C DAL function calls will redirect the call to appropriate I2C
  driver's API based on the argument "channel", which was pre-assigned to a
  particular I2C type and its instance.

  Refer table below for suitable UI2C DAL APIs for operations in different I2C types.
  ------------------------------------------------------------------------------------
  Unified I2C Wrapper \ I2C Type               CoreI2C                MSS I2C
  ------------------------------------------------------------------------------------
  UI2C_core_i2c_open				Initializes unified I2C               NA
                                    data structures with coreI2c
                                    instance
  UI2C_mss_i2c_open	                    NA	                        Initializes unified I2C
                                                                    data structures with MSS
                                                                    I2C instance.
  NA                                I2C_init	                          NA
  NA	                            I2C_channel_init	                  NA
  NA	                            NA	                            MSS_I2C_init
  NA	                            I2C_isr	                              NA
  UI2C_write	                    I2C_write	                    MSS_I2C_write
  UI2C_read	                        I2C_read	                    MSS_I2C_read
  UI2C_write_read	                I2C_write_read	                MSS_I2C_write_read
  UI2C_get_status	                I2C_get_status	                MSS_I2C_get_status
  UI2C_wait_complete	            I2C_wait_complete	            MSS_I2C_wait_complete
  UI2C_set_slave_tx_buffer	        I2C_set_slave_tx_buffer	        MSS_I2C_set_slave_tx_buffer
  UI2C_set_slave_rx_buffer	        I2C_set_slave_rx_buffer	        MSS_I2C_set_slave_rx_buffer
  UI2C_set_slave_mem_offset_length	I2C_set_slave_mem_offset_length	MSS_I2C_set_slave_mem_offset_length
  UI2C_register_write_handler	    I2C_register_write_handler	    MSS_I2C_register_write_handler
  UI2C_enable_slave_rx	            I2C_enable_slave_rx	            MSS_I2C_enable_slave_rx
  UI2C_set_slave_second_addr	    I2C_set_slave_second_addr	          NA
  UI2C_disable_slave_second_addr	I2C_disable_slave_second_addr	      NA
  UI2C_set_gca	                    I2C_set_gca	                    MSS_I2C_set_gca
  UI2C_clear_gca	                I2C_clear_gca	                MSS_I2C_clear_gca
  UI2C_smbus_init	                I2C_smbus_init	                MSS_I2C_smbus_init
  UI2C_enable_smbus_irq	            I2C_enable_smbus_irq	        MSS_I2C_enable_smbus_irq
  UI2C_disable_smbus_irq	        I2C_disable_smbus_irq	        MSS_I2C_disable_smbus_irq
  UI2C_suspend_smbus_slave	        I2C_suspend_smbus_slave	        MSS_I2C_suspend_smbus_slave
  UI2C_reset_smbus	                I2C_reset_smbus	                MSS_I2C_reset_smbus
  UI2C_set_smsbus_alert	            I2C_set_smsbus_alert	        MSS_I2C_set_smsbus_alert
  NA	                            I2C_get_irq_status()	             NA
  NA	                                   NA	                    I2C0_IRQHandler
  NA	                                   NA	                    I2C1_IRQHandler
  Note: NA - Not applicable (or) Not supported
 *//*=========================================================================*/
#ifndef __UI2C_DAL_H_
#define __UI2C_DAL_H_

#include <stdint.h>

/* Prevent compiler errors due to redefinition of VLNV constants in ui2c_dal_cfg.h */
#ifdef CORE_VENDOR
#undef CORE_VENDOR
#endif
#ifdef CORE_LIBRARY
#undef CORE_LIBRARY
#endif
#ifdef CORE_NAME
#undef CORE_NAME
#endif
#ifdef CORE_VERSION
#undef CORE_VERSION
#endif

/* Undefine the VLNV constants before and after including ui2c_dal_cfg.h */
#include "ui2c_dal_cfg.h"

/* The VLNV constants defined in ui2c_dal_cfg.h are not required.*/
#undef CORE_VENDOR
#undef CORE_LIBRARY
#undef CORE_NAME
#undef CORE_VERSION

#if(UI2C_CORE_I2C_ENABLED)
#include "../CoreI2C/core_i2c.h"
#endif
#if(UI2C_MSS_I2C_ENABLED)
#include "../mss_i2c/mss_i2c.h"
#include "../../CMSIS/mss_assert.h"
#endif


#ifdef __cplusplus
extern "C" {
#endif

/*-------------------------------------------------------------------------*//**
  The UI2C_RELEASE_BUS constant is used to specify the options parameter to
  functions UI2C_read(), UI2C_write() and UI2C_write_read() to indicate
  that a STOP bit must be generated at the end of the I2C transaction to release
  the bus.
*/
#define UI2C_RELEASE_BUS     0x00u

/*-------------------------------------------------------------------------*//**
  The UI2C_HOLD_BUS constant is used to specify the options parameter to
  functions UI2C_read(), UI2C_write() and UI2C_write_read() to indicate
  that a STOP bit must not be generated at the end of the I2C transaction in
  order to retain the bus ownership. This will cause the next transaction to
  begin with a repeated START bit and no STOP bit between the transactions.
*/
#define UI2C_HOLD_BUS        0x01u

/*-------------------------------------------------------------------------*//**
  The UI2C_SMBALERT_IRQ and UI2C_SMBSUS_IRQ are used by SMBus interrupt enable
  and disable functions.
*/
#define UI2C_SMBALERT_IRQ       0x01u
#define UI2C_SMBSUS_IRQ         0x02u

/*-------------------------------------------------------------------------*//**
  I2C types.
  This enumeration lists the types of I2Cs supported by UI2C DAL. Type of the
  I2C which will be passed to UI2C_Open() call should be any of the valid
  I2C types in this enumeration.
*/
typedef enum {
    UI2C_INVALID   = 0U,
    UI2C_CORE_I2C  = 1U,
    UI2C_MSS_I2C   = 2U,
    UI2C_LAST      = 3U
} ui2c_type_t;

/*-------------------------------------------------------------------------*//**
  The ui2c_status_t type is used to report the status of I2C transactions.
  This type is common for all I2C types supported.
 */
typedef enum ui2c_status
{
    UI2C_SUCCESS    = 0,
    UI2C_IN_PROGRESS,
    UI2C_FAILED,
    UI2C_SL_RCVING
} ui2c_status_t;

/*-------------------------------------------------------------------------*//**
  The ui2c_slave_handler_ret_t type is used by slave write handler functions
  to indicate whether the received data buffer should be released or not.
 */
typedef enum ui2c_slave_handler_ret {
    UI2C_REENABLE_SLAVE_RX = 0u,
    UI2C_PAUSE_SLAVE_RX = 1u
} ui2c_slave_handler_ret_t;

/*-------------------------------------------------------------------------*//**
  UI2C Slave write handler functions prototype.
  ------------------------------------------------------------------------------
  This defines the function prototype that must be followed by UI2C slave
  write handler functions. These functions are registered with the UI2C driver
  through the UI2C_register_write_handler() function.

  Declaring and Implementing Slave Write Handler Functions:
    Slave write handler functions should follow the following prototype:
    ui2c_slave_handler_ret_t write_handler
    (
       uint8_t * data, uint16_t size
    );
    The data parameter is a pointer to a buffer (received data buffer) holding
    the data written to the UI2C slave.
    The size parameter is the number of bytes held in the received data buffer.
    Handler functions must return one of the following values:
        UI2C_REENABLE_SLAVE_RX
        UI2C_PAUSE_SLAVE_RX.
    If the handler function returns UI2C_REENABLE_SLAVE_RX, the driver will
    release the received data buffer and allow further I2C write transactions to
    the I2C slave to take place.
    If the handler function returns UI2C_PAUSE_SLAVE_RX, the I2C slave will respond
    to subsequent write requests with a non-acknowledge bit (NACK), until the
    received data buffer content has been processed by some other part of the
    software application.
    A call to UI2C_enable_slave_rx() is required at some point after returning
    UI2C_PAUSE_SLAVE_RX in order to release the received data buffer so it can be
    used to store data received by subsequent I2C write transactions.
*/
typedef ui2c_slave_handler_ret_t (*ui2c_slave_wr_handler_t)( uint8_t *, uint16_t );

/*-------------------------------------------------------------------------*//**
  UI2C channel.
  This type definition is for creating I2C channels that associate with the
  supported type of I2C instances. You can create an I2C channel of this type
  and associate it with the I2C type by calling corresponding open function.
  This channel can be used for all further transactions on that
  particular I2C instance.
*/

typedef struct ui2c_channel
{
    /* One of UI2C_CORE_I2C or UI2C_MSS_I2C */
    ui2c_type_t i2c_type;
    union
    {
#if ( UI2C_CORE_I2C_ENABLED )
        /* pointer to a CoreI2C instance structure */
        i2c_instance_t        * core_i2c;
#endif
#if ( UI2C_MSS_I2C_ENABLED )
        /* pointer to a MSS_I2C instance structure */
        mss_i2c_instance_t    * mss_i2c;
#endif
    }instance;
    ui2c_slave_wr_handler_t slave_write_handler ;
} ui2c_channel_t;

#if ( UI2C_CORE_I2C_ENABLED )
/*-------------------------------------------------------------------------*//**
  The UI2C_core_i2c_open function opens a communication channel that can be
  used to interact with a specific CoreI2C instance. This function initializes
  the channel specified by the channel parameter and associates the CoreI2C
  instance specified by the instance parameter with that channel.

  Note:  You must call the CoreI2C driver’s I2C_init() function to
         initialize the CoreI2C instance structure before calling the
         UI2C_core_i2c_open() function.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param instance
    The instance parameter is a pointer to an i2c_instance_t data structure
    that identifies the CoreI2C instance you want to assign to a UI2C
    DAL channel.
    Note: The CoreI2C driver defines the i2c_instance_t data structure
          type. You must call the CoreI2C driver’s I2C_init() function
          to initialize the CoreI2C instance structure before calling
          the UI2C_core_i2c_open() function.
  @return
    This function does not return a value.
 */
void
UI2C_core_i2c_open
(
    ui2c_channel_t *channel,
    i2c_instance_t *instance
);
#endif

#if ( UI2C_MSS_I2C_ENABLED )
/*-------------------------------------------------------------------------*//**
  The UI2C_mss_i2c_open function opens a communication channel that can be
  used to interact with a specific MSS I2C instance. This function initializes
  the channel specified by the channel parameter and associates the MSS I2C
  instance specified by the instance parameter with that channel.

  Note:  You must call the CoreI2C driver’s MSS_I2C_init() function to
         initialize the MSS I2C instance structure before calling the
         UI2C_mss_i2c_open() function.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param instance
    The instance parameter is a pointer to a mss_i2c_instance_t data structure
    that identifies the MSS I2C instance you want to assign to a UI2C
    DAL channel.
    Note: The MSS I2C driver defines the mss_i2c_instance_t data structure
          type. You must call the MSS I2C driver’s MSS_I2C_init() function
          to initialize the MSS I2C instance structure before calling
          the UI2C_mss_i2c_open() function.
  @return
    This function does not return a value.
 */
void
UI2C_mss_i2c_open
(
    ui2c_channel_t *channel,
    mss_i2c_instance_t *instance
);
#endif

/*-------------------------------------------------------------------------*//**
  UI2C master write function.
  ------------------------------------------------------------------------------
  This function initiates an I2C master write transaction. This function returns
  immediately after initiating the transaction. The content of the write buffer
  passed as parameter should not be modified until the write transaction
  completes. It also means that the memory allocated for the write buffer should
  not be freed or go out of scope before the write completes. You can check for
  the write transaction completion using the UI2C_status() function.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param serial_addr:
    This parameter specifies the serial address of the target I2C device.

  @param write_buffer:
    This parameter is a pointer to a buffer holding the data to be written to
    the target I2C device.
    Care must be taken not to release the memory used by this buffer before the
    write transaction completes. For example, it is not appropriate to return
    from a function allocating this buffer as an array variable before the write
    transaction completes as this would result in the buffer's memory being
    de-allocated from the stack when the function returns. This memory could
    then be subsequently reused and modified causing unexpected data to be
    written to the target I2C device.

  @param write_size:
    Number of bytes held in the write_buffer to be written to the target I2C
    device.

  @param options:
    The options parameter is used to indicate if the I2C bus should be released
    on completion of the write transaction. Using the UI2C_RELEASE_BUS
    constant for the options parameter causes a STOP bit to be generated at the
    end of the write transaction causing the bus to be released for other I2C
    devices to use. Using the UI2C_HOLD_BUS constant as options parameter
    prevents a STOP bit from being generated at the end of the write
    transaction, preventing other I2C devices from initiating a bus transaction.
  @return
    This function does not return a value.
*/
void
UI2C_write
(
    ui2c_channel_t *channel,
    uint8_t serial_addr,
    const uint8_t *write_buffer,
    uint16_t write_size,
    uint8_t options
);

/*-------------------------------------------------------------------------*//**
  UI2C master read.
  ------------------------------------------------------------------------------
  This function initiates an I2C master read transaction. This function returns
  immediately after initiating the transaction.
  The content of the read buffer passed as parameter should not be modified
  until the read transaction completes. It also means that the memory allocated
  for the read buffer should not be freed or go out of scope before the read
  completes. You can check for the read transaction completion using the
  UI2C_status() function.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param serial_addr:
    This parameter specifies the serial address of the target I2C device.

  @param read_buffer
    Pointer to a buffer where the data received from the target device will be
    stored.
    Care must be taken not to release the memory used by this buffer before the
    read transaction completes. For example, it is not appropriate to return
    from a function allocating this buffer as an array variable before the read
    transaction completes as this would result in the buffer's memory being
    de-allocated from the stack when the function returns. This memory could
    then be subsequently reallocated resulting in the read transaction
    corrupting the newly allocated memory.

  @param read_size:
    This parameter is the number of bytes to read from the target device. This
    size must not exceed the size of the read_buffer buffer.

  @param options:
    The options parameter is used to indicate if the I2C bus should be released
    on completion of the read transaction. Using the UI2C_RELEASE_BUS
    constant for the options parameter causes a STOP bit to be generated at the
    end of the read transaction causing the bus to be released for other I2C
    devices to use. Using the UI2C_HOLD_BUS constant as options parameter
    prevents a STOP bit from being generated at the end of the read transaction,
    preventing other I2C devices from initiating a bus transaction.

  @return
    This function does not return a value.
*/
void
UI2C_read
(
    ui2c_channel_t *channel,
    uint8_t serial_addr,
    uint8_t *read_buffer,
    uint16_t read_size,
    uint8_t options
);

/*-------------------------------------------------------------------------*//**
  UI2C master write-read
  ------------------------------------------------------------------------------
  This function initiates an I2C write-read transaction where data is first
  written to the target device before issuing a restart condition and changing
  the direction of the I2C transaction in order to read from the target device.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param serial_addr:
    This parameter specifies the serial address of the target I2C device.

  @param addr_offset:
    This parameter is a pointer to the buffer containing the data that will be
    sent to the slave during the write phase of the write-read transaction. This
    data is typically used to specify an address offset specifying to the I2C
    slave device what data it must return during the read phase of the
    write-read transaction.

  @param offset_size:
    This parameter specifies the number of offset bytes to be written during the
    write phase of the write-read transaction. This is typically the size of the
    buffer pointed to by the addr_offset parameter.

  @param read_buffer:
    This parameter is a pointer to the buffer where the data read from the I2C
    slave will be stored.

  @param read_size:
    This parameter specifies the number of bytes to read from the target I2C
    slave device. This size must not exceed the size of the buffer pointed to by
    the read_buffer parameter.

  @param options:
    The options parameter is used to indicate if the I2C bus should be released
    on completion of the write-read transaction. Using the UI2C_RELEASE_BUS
    constant for the options parameter causes a STOP bit to be generated at the
    end of the write-read transaction causing the bus to be released for other
    I2C devices to use. Using the UI2C_HOLD_BUS constant as options parameter
    prevents a STOP bit from being generated at the end of the write-read
    transaction, preventing other I2C devices from initiating a bus transaction.

  @return
    This function does not return a value.
*/
void
UI2C_write_read
(
    ui2c_channel_t *channel,
    uint8_t serial_addr,
    const uint8_t *addr_offset,
    uint16_t offset_size,
    uint8_t *read_buffer,
    uint16_t read_size,
    uint8_t options
);

/*-------------------------------------------------------------------------*//**
  UI2C status
  ------------------------------------------------------------------------------
  This function indicates the current state of a I2C instance.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    The return value indicates the current state of a I2C instance or the
    outcome of the previous transaction if no transaction is in progress.
    Possible return values are:
      UI2C_SUCCESS
        The last I2C transaction has completed successfully.
      UI2C_IN_PROGRESS
        There is an I2C transaction in progress.
      UI2C_FAILED
        The last I2C transaction failed.
      UI2C_SL_RCVING
        I2C slave is still receiving.
*/
ui2c_status_t
UI2C_get_status
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  Wait for I2C transaction completion.
  ------------------------------------------------------------------------------
  This function waits for the current I2C transaction to complete. The return
  value indicates whether the last I2C transaction was successful, or is still
  in progress, or failed.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    The return value indicates the current state of a I2C instance or the
    outcome of the previous transaction if no transaction is in progress.
    Possible return values are:
      UI2C_SUCCESS
        The last I2C transaction has completed successfully.
      UI2C_IN_PROGRESS
        There is an I2C transaction in progress.
      UI2C_FAILED
        The last I2C transaction failed.
      UI2C_SL_RCVING
        I2C slave is still receiving.
*/
ui2c_status_t
UI2C_wait_complete
(
    ui2c_channel_t *channel
);

/*******************************************************************************
 *******************************************************************************
 *
 *                           Slave specific functions
 *
 * The following functions are only used within the implementation of an I2C
 * slave device.
 */

/*-------------------------------------------------------------------------*//**
  UI2C slave transmit buffer configuration.
  ------------------------------------------------------------------------------
  This function specifies the memory buffer holding the data that will be sent
  to the I2C master when this I2C instance is the target of an I2C read or
  write-read transaction.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param tx_buffer:
    This parameter is a pointer to the memory buffer holding the data to be
    returned to the I2C master when this I2C instance is the target of an
    I2C read or write-read transaction.

  @param tx_size:
    Size of the transmit buffer pointed to by the tx_buffer parameter.

  @return
    This function does not return a value.
*/
void
UI2C_set_slave_tx_buffer
(
    ui2c_channel_t *channel,
    uint8_t *tx_buffer,
    uint16_t tx_size
);

/*-------------------------------------------------------------------------*//**
  UI2C slave receive buffer configuration.
  ------------------------------------------------------------------------------
  This function specifies the memory buffer that will be used by the I2C
  instance to receive data when it is a slave. This buffer is the memory where
  data will be stored when the MSS I2C is the target of an I2C master write
  transaction (i.e. when it is the slave).
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param rx_buffer:
    This parameter is a pointer to the memory buffer allocated by the caller
    software to be used as a slave receive buffer.

  @param rx_size:
    Size of the slave receive buffer. This is the amount of memory that is
    allocated to the buffer pointed to by rx_buffer.
    Note:   This buffer size will indirectly specify the maximum I2C write
            transaction length this I2C instance can be the target of. This
            is because this I2C instance will respond to further received
            bytes with a non-acknowledge bit (NACK) as soon as its receive
            buffer is full. This will cause the write transaction to fail.

  @return
    This function does not return a value.
*/
void
UI2C_set_slave_rx_buffer
(
    ui2c_channel_t *channel,
    uint8_t *rx_buffer,
    uint16_t rx_size
);

/*-------------------------------------------------------------------------*//**
  UI2C slave memory offset length configuration.
  ------------------------------------------------------------------------------
  This function is used as part of the configuration of a I2C instance for
  operation as a slave supporting write-read transactions. It specifies the
  number of bytes expected as part of the write phase of a write-read
  transaction. The bytes received during the write phase of a write-read
  transaction will be interpreted as an offset into the slave's transmit buffer.
  This allows random access into the I2C slave transmit buffer from a remote
  I2C master.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param offset_length:
    The offset_length parameter configures the number of bytes to be interpreted
    by the I2C slave as a memory offset value during the write phase of
    write-read transactions.

  @return
    This function does not return a value.
*/
void
UI2C_set_slave_mem_offset_length
(
    ui2c_channel_t *channel,
    uint8_t offset_length
);

/*-------------------------------------------------------------------------*//**
  UI2C write handler registration.
  ------------------------------------------------------------------------------
  Register the function that will be called to process the data written to this
  I2C instance when it is the slave in an I2C write transaction.
  Note: The write handler is not called as a result of a write-read transaction.
        The write data of a write read transaction is interpreted as an offset
        into the slave's transmit buffer and handled by the driver.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param handler:
      Pointer to the function that will process the I2C write request.

  @return
    This function does not return a value.
*/
void
UI2C_register_write_handler
(
    ui2c_channel_t *channel,
    ui2c_slave_wr_handler_t handler
);

/*-------------------------------------------------------------------------*//**
  UI2C slave receive enable.
  ------------------------------------------------------------------------------
  Enables the I2C slave to receive data when it is the target of an I2C write
  or write-read transaction.
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/
void
UI2C_enable_slave_rx
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  Set I2C slave second address.
  ------------------------------------------------------------------------------
  The function UI2C_set_slave_second_addr() sets second slave address for the
  I2C slave device. This is secondary slave address which might be required
  in certain application to enable fail-safe mechanism in system design.
  Note : This function is only supported by CoreI2C instance. Calling this
         function for MSS I2C instance will not have any affect
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param second_slave_addr:
    The second_slave_addr parameter is secondary slave address of the I2C device.

  @return
    This function does not return a value.
 */
void
UI2C_set_slave_second_addr
(
    ui2c_channel_t *channel,
    uint8_t second_slave_addr
);

/*-------------------------------------------------------------------------*//**
  Disable second slave address.
  ------------------------------------------------------------------------------
  The function UI2C_disable_slave_second_addr() disables second slave address of
  the I2C device. This is slave function and require only in case of specific
  application.
  Note : This function is only supported by CoreI2C instance. Calling this
         function for MSS I2C instance will not have any affect
  ------------------------------------------------------------------------------
  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
 */
void
UI2C_disable_slave_second_addr
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  The UI2C_set_gca() function is used to set general call acknowledgement
  bit in slave device. This allows CoreI2C slave device to respond
  to general call or broadcast message from I2C master.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/

void
UI2C_set_gca
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  The UI2C_clear_gca() function is used to clear the general call
  acknowledgment bit of the slave device. This will disallow the I2C slave
  device to respond to any general call from the master.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/

void
UI2C_clear_gca
(
    ui2c_channel_t *channel
);

/*------------------------------------------------------------------------------
                      I2C SMBUS specific APIs
 ----------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*//**
  The UI2C_smbus_init() function enables SMBus timeouts and status logics.
  It sets PCLKx frequency to specify the SMBUS timeouts.
  Note: Frequency is only applicable to MSS I2C instance. Dummy value
        is passed in frequency for CoreI2C as frequency parameter is set
        during configuration of hardware instance in design. Firmware
        does not have control over SMBus time out frequency in case
        of CoreI2C.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param frequency
    The frequency specifies the PCLK frequency in MHz from 1 to 255.
    Note: Frequency is only applicable to MSS I2C instance. Dummy value
          is passed in frequency for CoreI2C as frequency parameter is set
          during configuration of hardware instance in design. Firmware
          does not have control over SMBus time out frequency in case
          of CoreI2C.

  @return
    This function does not return a value.
*/
void
UI2C_smbus_init
(
    ui2c_channel_t *channel,
    uint8_t frequency
);

/*-------------------------------------------------------------------------*//**
  The UI2C_enable_smbus_irq() function enables interrupt related to SMBus
  which is either SMBUS or SMBALERT interrupt.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param irq_type
    The irq_type specify the SMBUS interrupt which will be enabled.
    Following are two possible interrupts:
      UI2C_SMBALERT_IRQ
      UI2C_SMBUS_IRQ

  @return
    This function does not return a value.
*/
void
UI2C_enable_smbus_irq
(
    ui2c_channel_t *channel,
    uint8_t  irq_type
);

/*-------------------------------------------------------------------------*//**
  The UI2C_disable_smbus_irq() function disables interrupt related to SMBus
  which is either SMBUS or SMBALERT interrupt.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @param irq_type
    The irq_type specify the SMBUS interrupt which will be disabled.
    Following are two possible interrupts:
      UI2C_SMBALERT_IRQ
      UI2C_SMBUS_IRQ

  @return
    This function does not return a value.
*/
void
UI2C_disable_smbus_irq
(
    ui2c_channel_t *channel,
    uint8_t  irq_type
);

/*-------------------------------------------------------------------------*//**
  The function UI2C_suspend_smbus_slave() forces slave devices into power down
  or suspend mode. This will be used by I2C master.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/
void
UI2C_suspend_smbus_slave
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  The UI2C_reset_smbus() function resets SMBus device.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/
void
UI2C_reset_smbus
(
    ui2c_channel_t *channel
);

/*-------------------------------------------------------------------------*//**
  The UI2C_set_smbus_alert() function is used to force master communication
  by I2C slave device. This function is used in slave mode.

  @param channel:
    The channel parameter is a pointer to a ui2c_channel_t data structure.
    This function initializes the data structure with the data necessary to
    identify the I2C assigned to the channel. A pointer to the same data
    structure will be used in subsequent calls to other UI2C DAL functions
    in order to identify the channel that should be used by the called
    driver function.

  @return
    This function does not return a value.
*/
void
UI2C_set_smbus_alert
(
    ui2c_channel_t *channel
);

#ifdef __cplusplus
}
#endif

#endif  /* __UI2C_DAL_H_ */

