<?xml version="1.0" encoding="utf-8"?>


<!--****************************************************************************
* \file i2c.cypersonality
* \version 2.0
*
* \brief
* I2C personality description file.
*
********************************************************************************
* \copyright
* Copyright 2018-2020 Cypress Semiconductor Corporation
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*****************************************************************************-->

<Personality id="mxs40i2c" name="I2C" version="2.0" path="Communications" xmlns="http://cypress.com/xsd/cyhwpersonality_v1">
  <Dependencies>
    <IpBlock name="mxscb">
      <Param name="I2C" value="1" />
    </IpBlock>
    <Resource name="scb" used="true" />
  </Dependencies>
  <ExposedMembers />  
  <Parameters>  
    <!-- PDL documentation -->
    <ParamDoc id="pdlDoc" name="Configuration Help" group="Peripheral Documentation" default="file:///`${cy_libs_path()}`/docs/pdl_api_reference_manual/html/group__group__scb__i2c.html" linkText="Open I2C (SCB) Documentation" visible="true" desc="Opens the Peripheral Driver Library Documentation" />

    <ParamBool id="DeepSleepCapable" name="DeepSleepCapable" group="Internal" default="`${DEEPSLEEP eq 1}`" visible="false" editable="false" desc="This parameter specifies if SCB block can wakeup from Deep Sleep." />
    <ParamBool id="SlaveCapable" name="SlaveCapable" group="Internal" default="`${I2C_S eq 1}`" visible="false" editable="false" desc="This parameter specifies if SCB block supports Slave mode." />
    <ParamBool id="MasterCapable" name="MasterCapable" group="Internal" default="`${I2C_M eq 1}`" visible="false" editable="false" desc="This parameter specifies if SCB block supports Master mode." />
    <ParamBool id="MasterSlaveCapable" name="MasterCapable" group="Internal" default="`${I2C_M_S eq 1}`" visible="false" editable="false" desc="This parameter specifies if SCB block supports Master-Slave mode." />

    <!-- General -->
    <ParamChoice id="ModeUser" name="Mode" group="General" default="`${SlaveCapable ? &quot;CY_SCB_I2C_SLAVE&quot; : MasterCapable ? &quot;CY_SCB_I2C_MASTER&quot; : &quot;CY_SCB_I2C_MASTER_SLAVE&quot;}`" visible="true" editable="`${SlaveCapable ? (MasterCapable || MasterSlaveCapable) : MasterCapable ? (SlaveCapable || MasterSlaveCapable) : false}`" desc="This parameter defines the I2C operation mode as: the slave, master or master-slave.">
      <Entry name="Slave" value="CY_SCB_I2C_SLAVE" visible="`${SlaveCapable}`" />
      <Entry name="Master" value="CY_SCB_I2C_MASTER" visible="`${MasterCapable}`" />
      <Entry name="Master-Slave" value="CY_SCB_I2C_MASTER_SLAVE" visible="`${MasterSlaveCapable}`" />
    </ParamChoice>

    <ParamBool id="Slave" name="Slave" group="Internal" default="`${ModeUser ne CY_SCB_I2C_MASTER}`" visible="false" editable="false" desc="Enables Slave functionality." />
    <ParamBool id="Master" name="Master" group="Internal" default="`${ModeUser ne CY_SCB_I2C_SLAVE}`" visible="false" editable="false" desc="Enables Master functionality." />

    <ParamBool id="ManualDataRateCtrl" name="Manual Data Rate Control" group="General" default="false" visible="`${Master}`" editable="true" desc="This parameter enables the user to configure data rate ralated parameters for the master modes." />
    <ParamBool id="ManualDataRate" name="ManualDataRate" group="Internal" default="`${Master &amp;&amp; ManualDataRateCtrl}`" visible="false" editable="false" desc="This parameter enables the user to configure data rate ralated parameters for the master modes." />

    <ParamBool id="ManualDigitalFilter" name="Enable Digital Filter" group="Manual DataRate Control" default="true" visible="`${ManualDataRate}`" editable="true" desc="This parameter enables digital (3-tap median) filter on I2C input lines. An analog filter is disabled when digital filter is enabled and vice versa." />
    <ParamRange id="ManualLowPhaseDutyCycle" name="SCL Low Phase (SCB Clocks)" group="Manual DataRate Control" default="16" min="1" max="16" resolution="1" visible="`${ManualDataRate}`" editable="true" desc="This parameter defines how many SCB clocks are used to generate the SCL low phase (only applicable for the master modes)." />
    <ParamRange id="ManualHighPhaseDutyCycle" name="SCL High Phase (SCB Clocks)" group="Manual DataRate Control" default="9" min="1" max="16" resolution="1" visible="`${ManualDataRate}`" editable="true" desc="This parameter defines how many SCB clocks are used to generate the SCL high phase (only applicable for the master modes)." />

    <ParamRange id="DataRate" name="Data Rate (kbps)" group="General" default="100" min="1" max="1000" resolution="1" visible="`${!ManualDataRate}`" editable="true" desc="Data rate that I2C operates. Maximum data rate is 1000 kbps." />

    <ParamBool id="EnableTxFifo" name="Use TX FIFO" group="General" default="true" visible="true" editable="true" desc="This parameter defines if the TX FIFO capabilites are used. Usage of the TX FIFO reduces the possibility of clock stretching and interrupt overhead." />

    <ParamBool id="AcceptAddress" name="Accept Matching Address in RX FIFO" group="General" default="false" visible="`${Slave}`" editable="true" desc="This parameter determines whether to accept the match slave address in the RX FIFO or not. This feature is useful when more than one address support is required. The user has to register the callback function to handle the accepted addresses." />
    <ParamBool id="IsEnableRxFifoVisible" name="Is Enable Rx Fifo Visible" group="Internal" default="`${(ModeUser eq CY_SCB_I2C_MASTER) || !AcceptAddress}`" visible="false" editable="false" desc="This parameter specifies the visibility of EnableRxFifo parameter." />
    <ParamBool id="EnableRxFifo" name="Use RX FIFO" group="General" default="true" visible="`${IsEnableRxFifoVisible}`" editable="true" desc="This parameter defines if the RX FIFO capabilites are used. Usage of the RX FIFO reduces the possibility of clock stretching and interrupt overhead." />

    <ParamBool id="EnableWakeup" name="Enable Wakeup from Deep Sleep Mode" group="General" default="false" visible="`${DeepSleepCapable}`" editable="true" desc="This parameter enables the I2C to wake the system from Deep-Sleep when a slave address match occurs (only applicable for the slave mode)." />

    <!-- Slave -->
    <ParamRange id="SlaveAddress" name="Slave Address (7-bit)" group="Slave" default="8" min="8" max="120" resolution="1" visible="`${Slave}`" editable="true" desc="This parameter specifies the 7-bit right justified slave address.
    The range: 0x08-0x78." /> 
    <ParamRange id="SlaveAddressMask" name="Slave Address Mask (8-bit)" group="Slave" default="254" min="0" max="255" resolution="1" visible="`${Slave}`" editable="true" desc="This parameter specifies the slave address mask. The range: 0x00-0xFE.
    - Bit value 0 – excludes the bit from the address comparison. 
    - Bit value 1 – the bit needs to match with the corresponding bit of the I2C slave address." />
    
    <ParamBool id="AcceptGeneralCall" name="Accept General Call Address" group="Slave" default="false" visible="`${Slave}`" editable="true" desc="This parameter specifies whether to accept the general call address. The general call address is ACKed when accepted and NAKed otherwise (default). The user has to register the callback function to handle the general call address." />
    
    <!-- SCB I2C clock constraints -->
    <ParamString id="ScbClkMinMHz" name="ScbClkMinMHz" group="Internal" default="`${(DataRate &lt;= 100) ? 1.55 : ((DataRate &gt; 100) &amp;&amp; (DataRate &lt;= 400)) ? 7.82 : (Master ? 14.32 : 15.84)}`" visible="false" editable="false" desc="Minimum clock frequency to operate with desired data rate." />
    <ParamString id="ScbClkMaxMHz" name="ScbClkMaxMHz" group="Internal" default="`${Master ? ((DataRate &lt;= 100) ? 3.2 : ((DataRate &gt; 100) &amp;&amp; (DataRate &lt;= 400)) ? 10.0 : 25.8) : ((DataRate &lt;= 100) ? 12.8 : ((DataRate &gt; 100) &amp;&amp; (DataRate &lt;= 400)) ? 15.38 : 89.0)}`" visible="false" editable="false" desc="Maximum clock frequency to operate with desired data rate." />

    <!-- Connections -->
    <ParamSignal port="clock[0]" name="Clock" group="Connections" visible="true" desc="Clock that operates this block." canBeEmpty="false" >
      <Constraint type="REQUIRE" targetLocation="peri\[\d+\]\.div_.*" valid="`${!ManualDataRate}`" >
        <Parameter id="intDivider" severity="ERROR" reason="The clock frequency must be within the range `${ScbClkMinMHz}` - `${ScbClkMaxMHz}` MHz to operate with Data Rate `${DataRate}` kbps." valid="`${!ManualDataRate}`">
          <Range 
            min="`${ceil(getExposedMember(&quot;REF_LOCATION&quot;, &quot;frequency&quot;) * getExposedMember(&quot;REF_LOCATION&quot;, &quot;divider&quot;) / (ScbClkMaxMHz * 1000000))}`" 
            max="`${floor(getExposedMember(&quot;REF_LOCATION&quot;, &quot;frequency&quot;) * getExposedMember(&quot;REF_LOCATION&quot;, &quot;divider&quot;) / (ScbClkMinMHz * 1000000))}`" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation="peri\[\d+\]\.div_(16.5|24.5).*" valid="true" >
        <Parameter id="fracDivider" severity="ERROR" reason="Fractional divider must be 0 for I2C interface.">
          <Fixed value= "0" />
        </Parameter>
      </Constraint>
    <Constraint type="ACCEPT" targetLocation=".*" valid="`${ManualDataRate}`" />
    </ParamSignal>

    <ParamSignal port="i2c_scl[0]" name="SCL" group="Connections" visible="true" desc="Serial clock (SCL) is the master-generated I2C clock." canBeEmpty="false">
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="DEFAULT" reason="">
          <Fixed value="CY_GPIO_DM_OD_DRIVESLOW" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="INFO" reason="The pin Drive Mode parameter does not match expected.">
          <Fixed value="CY_GPIO_DM_OD_DRIVESLOW" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation=".*" valid="true" />
    </ParamSignal>
    <ParamSignal port="i2c_sda[0]" name="SDA" group="Connections" visible="true" desc="Serial data (SDA) is the I2C data signal." canBeEmpty="false">
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="DEFAULT" reason="">
          <Fixed value="CY_GPIO_DM_OD_DRIVESLOW" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="INFO" reason="The pin Drive Mode parameter does not match expected.">
          <Fixed value="CY_GPIO_DM_OD_DRIVESLOW" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation=".*" valid="true" />
    </ParamSignal>
    <ParamSignal port="tr_i2c_scl_filtered[0]" name="SCL Output (scl_trig)" group="Connections" visible="true" desc="This output allows monitoring of the SCL state. The connection capabilies are limited by the trigger mux. The typical connection is to TCPWM, which can be used to monitor the SCL low timeout." canBeEmpty="true" >
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="DEFAULT" reason="">
          <Fixed value="CY_GPIO_DM_STRONG_IN_OFF" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation="ioss\[\d+\]\.port\[\d+\]\.pin.*" valid="true" >
        <Parameter id="DriveModes" severity="INFO" reason="The pin Drive Mode parameter does not match expected.">
          <Fixed value="CY_GPIO_DM_STRONG_IN_OFF" />
        </Parameter>
      </Constraint>
      <Constraint type="ACCEPT" targetLocation=".*" valid="true" />
    </ParamSignal>

    <!-- Clock Frequency -->
    <ParamString id="sourceClock" name="sourceClock" group="Internal" default="`${getBlockFromSignal(&quot;clock[0]&quot;)}`" visible="false" editable="false" desc="Source Clock Resource" />
    <ParamRange  id="scbClkHz" name="scbClkHz" group="Internal" default="`${getExposedMember(sourceClock, &quot;frequency&quot;)}`" min="1" max="200000000" resolution="1" visible="false" editable="false" desc="SCB clock frequency in kHz" />

    <!--  I2C Master Duty Cycle constrains -->
    <ParamString id="i2c_solver" name="i2c_solver" group="Internal" default="`${runTcl(&quot;i2c_solver-2.0.tcl&quot;, Master ? &quot;Master&quot; : &quot;Slave&quot;, DataRate * 1000, scbClkHz)}`" visible="false" editable="false" desc="I2C master data rate configurator." />
    <ParamBool id="AutoDigitalFilter" name="Digital Filter" group="Internal" default="`${getTclVar(&quot;digitalFilter&quot;, i2c_solver)}`" visible="false" editable="false" desc="This parameter specifies to enable digital (3-tap median) fitler. An analog filter is disabled when digital filter is enabled. It is calculated by i2c_solver." />
    <ParamRange id="AutoLowPhaseDutyCycle" name="SCL Low Phase (SCB Clocks)" group="Internal" default="`${getTclVar(&quot;lowOversample&quot;, i2c_solver)}`" min="0" max="16" resolution="1" visible="false" editable="false" desc="This parameter defines how many SCB clocks are used to generate the SCL low phase (only applicable for the master modes). It is calculated by i2c_solver." /> 
    <ParamRange id="AutoHighPhaseDutyCycle" name="SCL High Phase (SCB Clocks)" group="Internal" default="`${getTclVar(&quot;highOversample&quot;, i2c_solver)}`" min="0" max="16" resolution="1" visible="false" editable="false" desc="This parameter defines how many SCB clocks are used to generate the SCL high phase (only applicable for the master modes). It is calculated by i2c_solver." />

    <ParamBool id="DigitalFilter" name="Digital Filter" group="Internal" default="`${ManualDataRate ? ManualDigitalFilter : AutoDigitalFilter}`" visible="false" editable="false" desc="This parameter specifies to enable digital (3-tap median) fitler. An analog filter is disabled when digital filter is enabled." />
    <ParamRange id="LowPhaseDutyCycle" name="SCL Low Phase (SCB Clocks)" group="Internal" default="`${ManualDataRate ? ManualLowPhaseDutyCycle : AutoLowPhaseDutyCycle}`" min="0" max="16" resolution="1" visible="false" editable="false" desc="This parameter defines how many SCB clocks are used to generate the SCL low phase (only applicable for the master modes)." />
    <ParamRange id="HighPhaseDutyCycle" name="SCL High Phase (SCB Clocks)" group="Internal" default="`${ManualDataRate ? ManualHighPhaseDutyCycle : AutoHighPhaseDutyCycle}`" min="0" max="16" resolution="1" visible="false" editable="false" desc="This parameter defines how many SCB clocks are used to generate the SCL high phase (only applicable for the master modes)." />

    <!-- Actual Data Rate -->
    <ParamRange id="actualDataRate" name="Actual Data Rate (kbps)" group="Actual Data Rate" default="`${Master ? (scbClkHz / ((LowPhaseDutyCycle + HighPhaseDutyCycle) * 1000)) : (((DataRate &lt; 100) || (DataRate eq 100)) ? 100 : ((DataRate &gt; 100) &amp;&amp; (DataRate &lt; 400) || (DataRate eq 400)) ? 400 : 1000)}`" min="0" max="10000" resolution="1" visible="true" editable="false" desc="The actual data rate displays the data rate at which the I2C operates with current settings. For the master modes actual data rate does not take into account the I2C bus charcteristics and may differ from the observed on the bus. If this is the case enable Manual Data Rate Control to configure/adjust data rate related parameters. Refer to the section I2C sub-section Oversampling and Bit Rate in the selected device TRM for more information." />
    <ParamRange id="sclLow" name="tLow (us)" group="Actual Data Rate" default="`${((1000000000.0 / scbClkHz) * LowPhaseDutyCycle)}`" min="0" max="4294967295" resolution="1" visible="`${Master}`" editable="false" desc="tLow parameter (the LOW period of the SCL clock, including falling edge)." />
    <ParamRange id="sclHigh" name="tHigh (us)" group="Actual Data Rate" default="`${((1000000000.0 / scbClkHz) * HighPhaseDutyCycle)}`" min="0" max="4294967295" resolution="1" visible="`${Master}`" editable="false" desc="tHigh parameter (the HIGH period of the SCL clock, including raising edge). tHigh value might be less than observed on the bus due to clock synchronization in the device. The device resets its internal counter of tHigh when it detects a low level on SCL line while expecting high level." />
    
    <ParamString id="ClkFreq" name="Clock Frequency" group="Actual Data Rate" default="`${(scbClkHz &lt; 1000000) ? (scbClkHz / 1000.0) . &quot; kHz&quot; : (scbClkHz / 1000000.0) . &quot; MHz&quot;}`" visible="true" editable="false" desc="Frequency of the connected clock" />

    <!-- Advanced-->
    <ParamBool id="inFlash" name="Store Config in Flash" group="Advanced" default="true" visible="true" editable="true" desc="Controls whether the configuration structure is stored in flash (const, true) or SRAM (not const, false)." />

    <!-- SCB instance number -->
    <ParamString id="InstNumber" name="InstNumber" group="Internal" default="`${getInstNumber(&quot;scb&quot;)}`" visible="false" editable="false" desc="SCB Instance name number." />

    <!-- Peripheral clock divider connection -->
    <ParamBool id="pclkOk" name="PCLK Valid" group="Internal" default="`${hasConnection(&quot;clock&quot;, 0) &amp;&amp; isBlockUsed(sourceClock)}`" visible="false" editable="false" desc="Checks whether there is a PCLK connected and enabled." />
    <ParamString id="pclkDst" name="PCLK Destination" group="Internal" default="PCLK_SCB`${InstNumber}`_CLOCK" visible="false" editable="false" desc="Generates PCLK connection define." />
  </Parameters>
  
  <DRCs>  
    <!--SlaveAddressMask DRCs-->
    <DRC type="ERROR" paramId="SlaveAddressMask" text="The I2C slave address mask must be even." condition="`${(SlaveAddressMask % 2) ne 0}`" />
    <DRC type="ERROR" paramId="clock[0]" text="The actual data rate `${actualDataRate}` kpbs is greater than desired `${DataRate}` kpbs. Increase clock divider to produce lower clock frequency or adjust desired Data Rate." condition="`${Master ? (!ManualDataRate &amp;&amp; (actualDataRate &gt; DataRate) ) : false}`" />
  </DRCs>
  
  <ConfigFirmware>
    <ConfigInclude value="cy_scb_i2c.h" include="true" />
    <ConfigInclude value="cy_sysclk.h" include="`${pclkOk}`" />
    <ConfigInclude value="cyhal_hwmgr.h" include="true" guard="defined (CY_USING_HAL)" />
    
    <ConfigDefine name="`${INST_NAME}`_HW" value="SCB`${InstNumber}`" public="true" include="true" />
    <ConfigDefine name="`${INST_NAME}`_IRQ" value="scb_`${InstNumber}`_interrupt_IRQn" public="true" include="true" />
    <ConfigStruct name="`${INST_NAME}`_config" type="cy_stc_scb_i2c_config_t" const="`${inFlash}`" public="true" include="true">
      <Member name="i2cMode" value="`${ModeUser}`" />  
      <Member name="useRxFifo" value="`${IsEnableRxFifoVisible ? (EnableRxFifo ? &quot;true&quot; : &quot;false&quot;) : &quot;false&quot;}`" />    
      <Member name="useTxFifo" value="`${EnableTxFifo ? &quot;true&quot; : &quot;false&quot;}`" />    
      <Member name="slaveAddress" value="`${Slave ? SlaveAddress : &quot;0U&quot;}`" />
      <Member name="slaveAddressMask" value="`${Slave ? SlaveAddressMask : &quot;0U&quot;}`" />
      <Member name="acceptAddrInFifo" value="`${Slave ? (AcceptAddress ? &quot;true&quot; : &quot;false&quot;) : &quot;false&quot;}`" />
      <Member name="ackGeneralAddr" value="`${Slave ? (AcceptGeneralCall ? &quot;true&quot; : &quot;false&quot;) : &quot;false&quot;}`" /> 
      <Member name="enableWakeFromSleep" value="`${EnableWakeup}`" />
      <Member name="enableDigitalFilter" value="`${DigitalFilter ? &quot;true&quot; : &quot;false&quot;}`" /> 
      <Member name="lowPhaseDutyCycle" value="`${LowPhaseDutyCycle}`" /> 
      <Member name="highPhaseDutyCycle" value="`${HighPhaseDutyCycle}`" /> 
    </ConfigStruct>
    
    <ConfigStruct name="`${INST_NAME}`_obj" type="cyhal_resource_inst_t" const="true" public="true" include="true" guard="defined (CY_USING_HAL)">
      <Member name="type" value="CYHAL_RSC_SCB" />
      <Member name="block_num" value="`${getInstNumber(&quot;scb&quot;)}`U" />
      <Member name="channel_num" value="0U" />
    </ConfigStruct>
    
    <ConfigInstruction value="Cy_SysClk_PeriphAssignDivider(`${pclkDst}`, `${getExposedMember(sourceClock, &quot;clockSel&quot;)}`);" include="`${pclkOk}`" />
    <ConfigInstruction value="cyhal_hwmgr_reserve(&amp;`${INST_NAME}`_obj);" include="true" guard="defined (CY_USING_HAL)" />
  </ConfigFirmware>
</Personality>