'#Uses "..\include\Global.inc"
'#Uses "..\include\Const.inc"
'#Uses "..\classes\FunctionClass.cls"
'#Uses "..\classes\ParameterClass.cls"
'#Uses "..\include\Format.inc"
'#Uses "..\include\PORT.inc"

Option Explicit

'*****************************************************************************
' Module:
'        I2C
'-----------------------------------------------------------------------------
' Description:
'        This module contains all functions that are used in the 
'        I2C dialog script and in the I2C codegenerator script.
'
'-----------------------------------------------------------------------------
' History:
'                 
'        Rev. Author         Date        Description
'        ---------------------------------------------------------------------
'        1.0   ahe         21.07.00     final version for C161PI
'
'        ---------------------------------------------------------------------
'        1.1   ahe         11.04.01     final version for 
'                                       - C161PI
'                                       - C161CS/JC/JI
'                                       no changes
'
'*****************************************************************************


'*****************************************************************************
' Constants
'*****************************************************************************
Global Const I2C_PRECISION = "0.000"

'*****************************************************************************
'Description:
'        For each function which should be used for this module a line 
'        "If (Not func.AddFunction .." must be insert in this function.
'        For each parameter that should be used for this function a  
'        line "If (Not func.AddParameter .." must be insert in this function.
'
'        Note:
'        For each added function a project variable with the name 
'        "I2C_NAME_Functionname" must be exist in the *.vars file. 
'-----------------------------------------------------------------------------
'Parameters:
'        func             reference to the FunctionClass object
'        r                reference to the Registers object
'-----------------------------------------------------------------------------
'Returns:
'        True            on successfull operation
'        False           else
'*****************************************************************************
Public Function RefreshFunctionDescriptions(vIndex As Variant, func As FunctionClass, r As ProjectData) As Boolean
  On Error Resume Next 

  RefreshFunctionDescriptions = False

  Dim sDescription As String
  Dim sReturnValue As String
  Dim sVarPre As String
  Dim sRegPre As String
  Dim sFctName As String

  sVarPre = "I2C"
  sRegPre = "IC"

  ' for each function of this module the property AddFunction must be called
  '
  ' AddFunction(sFuncName As String, sFuncType As String, sFuncDescription As String, 
  '             sReturnvalue As String, lSort As Long) As Boolean
  '
  ' sFuncName          | String | function name as key (use the name of the variable 
  '                               for the function name e.g. SSC_NAME_Init) 
  ' sFuncType          | String | type of the function
  ' sFuncDescription   | String | description of the function
  ' sReturnvalue       | String | description of the return value
  ' lSort              | Long   | ' sort of the function (0 => macro, 1 => function, 2 => ISR, 3 => TRAP)

    ' for each parameter of a function the property AddParameter must be called
    '
    'AddParameter(sParName As String, sPar As String, sParType As String, sParDescription As String) As Boolean    
    '
    ' sParName         | String | parameter name (key)
    ' sPar             | String | parameter name
    ' sParType         | String | type of the parameter
    ' sParDescription  | String | description of the parameter


  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_Init
  '------------------------------------------------------------------------------------------------
  sDescription = GetGeneralInitDescription(sVarPre)
  
  sReturnValue = "None" 
  
  If (Not func.AddFunction(sVarPre & "_NAME_Init", "void", sDescription, sReturnValue, 1)) Then Exit Function

  
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "SetDeviceAddr"
  sDescription = "This function sets the " & sVarPre & " device address "     & _
                 "and the address mode. "                                     & _
                 "This device address is the address by wich "                & _
                 "this device can be selected in slave or "                   & _
                 "multi-master mode. "                                        & _
                 "The device is also selected when it "                       & _
                 "receives a general call address (00h) "                     & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 "The address register is set by the parameter"               & vbcrlf & _
                 "uwAddress"                                                  & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 "The address mode is set by the parameter"                   & vbcrlf & _
                 "uwAddressMode"                                              & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 "The following definitions for uwAddressMode are available:" & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 r.v(sVarPre & "_PARA_ADR7") & "  selects 7-bit address mode" & vbcrlf & _
                 r.v(sVarPre & "_PARA_ADR10") & " selects 10-bit address mode"

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "address value"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "uwAddress", "uword", sDescription)) Then Exit Function
    sDescription = "address mode"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "uwAddressMode", "uword", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GetDeviceAddr"
  sDescription = "This macro returns the device address from the " & sVarPre & " address " & _
                 "register (" & sRegPre & "ADR). "                                         & vbcrlf & _
                 "This is the internal address of this device."

  sReturnValue = "value of register " & sRegPre & "ADR"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "SelectChannel"
  sDescription = "This macro selects " & sVarPre & " baudrate and channels."        & vbcrlf & _
                 ""                                                                 & vbcrlf & _
                 "The register for the baudrate is loaded by "                      & _
                 "the parameter:"                                                   & vbcrlf & _
                 "Baudrate"                                                         & vbcrlf & _
                 ""                                                                 & vbcrlf & _
                 "The channel is selected by the parameter:"                        & vbcrlf & _
                 "Channel"                                                          & vbcrlf & _
                 ""                                                                 & vbcrlf & _
                 "The following definitions for Channel are available:"             & vbcrlf & _
                 r.v(sVarPre & "_PARA_CHANNEL0")                                    & vbcrlf & _
                 r.v(sVarPre & "_PARA_CHANNEL1")                                    & vbcrlf & _
                 ""                                                                 & vbcrlf & _
                 "Note:"                                                            & vbcrlf & _
                 "To select both channels simultaneously the macro is "             & _
                 "used as follows:"                                                 & vbcrlf & _
                 r.v(sVarPre & "_NAME_SelectChannel") & "("                         & _
                 FormatTextOutput(r.v(sRegPre & "CFG_BRP"), "H2")                   & _
                 "," & r.v(sVarPre & "_PARA_CHANNEL0") & " + "                      & _
                 r.v(sVarPre & "_PARA_CHANNEL1") & ");"


  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
    sDescription = "8 bit value for the baudrate prescaler"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "Baudrate", "", sDescription)) Then Exit Function
    sDescription = "name of the Channel to be used"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "Channel", "", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ResetStatus"
  sDescription = "This macro resets the selected bit in the status register " & _
                 sRegPre & "ST of the " & sVarPre & " module"                 & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 "The bit is seleccted by the parameter:"                     & vbcrlf & _
                 "Statusbit"                                                  & vbcrlf & _
                 ""                                                           & vbcrlf & _
                 "The following definitions for Statusbit are available:"     & vbcrlf & _
                 "AL"                                                         & vbcrlf & _
                 "IRQD"                                                       & vbcrlf & _
                 "IRQP"

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
    sDescription = "Bit to reset"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "Statusbit", "", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GetStatus"
  sDescription = "This macro returns the status of the " & sVarPre                      & _
                 " module (" & sRegPre & "ST). "                                        & _
                 "For further information about the bits of the status "                & _
                 "register refer to the user's manual."

  sReturnValue = "the contents of " & sRegPre & "ST"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "WriteData"
  sDescription = "This macro writes data to the " & sVarPre & " receive transmit buffer "  & _
                 "(" & sRegPre & "RTB). In master mode, it initiates a data transfer "     & _
                 "if the " & sVarPre & " bus was claimed before calling this macro. "      & _
                 "To start transmission of the first byte in master mode, "                & _
                 "the macro " & r.v(sVarPre & "_NAME_WriteData")                           & _
                 " has to be called before a start condition was set with "                & _
                 "the macro " & r.v(sVarPre & "_NAME_GenStartCond") & ". "                 & _
                 "In slave mode, this macro has to be called before the "                  & _
                 "master will start the transmission."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
    sDescription = "8 bit data to be transmitted"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "Data", "", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ReadData"
  sDescription = "In master mode this macro reads out the contents of the "                   & _
                 sVarPre & " receive transmit buffer (" & sRegPre & "RTB) and starts a new "  & _
                 "transmission if no stop condition occured."

  sReturnValue = "value of the register " & sRegPre & "RTB"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GetControlReg"
  sDescription = "This macro returns the " & sVarPre & " control register (" & sRegPre & "CON). " & _
                 "For further information about the bits of the status "                          & _
                 "register refer to the user's manual."

  sReturnValue = "contents of " & sRegPre & "CON"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GenStartCond"
  sDescription = "This macro is used to generate the start condition in master "              & _
                 "and multi master mode. It has to be used after the first "                  & _
                 "data byte has been written to the " & sVarPre & " transmit receive buffer " & _
                 "(" & sRegPre & "RTB)."                                        

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GenStopCond"
  sDescription = "This macro is used to generate the stop condition in master "               & _
                 "and multi master mode. It has to be used after the last data "              & _
                 "byte has been transmitted or received. "                                    & _
                 "After receiving of the last byte, this macro is to be called "              & _
                 "after the byte was read out of the register " & sRegPre & "RTB and before " & _
                 "the bus will be released by clearing the IRQD bit to prevent "              & _
                 "the master from starting a new clock cycle."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "EnableACK"
  sDescription = "This macro is used to enable the acknoledge pulse generation. " & _
                 "Normally the receiving device gives an acknowledge to the "     & _
                 "transmitter. Only the last byte has not to be acknowledged."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "DisableACK"
  sDescription = "This macro is used to disable the acknoledge pulse generation. " & _
                 "Normally the receiving device gives an acknowledge to the "      & _
                 "transmitter. Only the last byte has not to be acknowledged."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "GenRSC"
  sDescription = "This macro is used to generate a repeated start condition "   & _
                 "in master and multi-master mode. "                            & _
                 "This macro is to be called before the address is written to " & _
                 "the " & sVarPre & " receive transmit buffer."                            

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "SetDataDirRx"
  sDescription = "This macro resets the transmit select bit TRX in " & sRegPre & "CON. " & _
                 "It has to be set, if one or more bytes will be received."             

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "SetDataDirTx"
  sDescription = "This macro sets the transmit select bit TRX in " & sRegPre & "CON. " & _
                 "It will be set automatically when writing to the "                   & _
                 "receive transmit buffer."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "EnAutoIntRst"
  sDescription = "This macro resets the auto interrupt reset disable bit "              & _
                 "AIRDIS in " & sRegPre & "CON. IRQD is automatically cleared upon a "  & _
                 "read/write access to the " & sVarPre & " receive transmit buffer "    & _
                 "(" & sRegPre & "RTB). It has to be enabled, if the data transfer is " & _
                 "made automatically in the ISR indicated by IRQD"

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "DisAutoIntRst"
  sDescription = "This macro sets the auto interrupt reset disable bit AIRDIS "              & _
                 "in " & sRegPre & "CON. IRQD must explicitily cleared via software. "       & _
                 "Before reading the last byte from the " & sVarPre & " receive transmit "   & _
                 "buffer " & sRegPre & "RTB in receive mode, this macro is to be called "    & _
                 "to prevent starting a new clock period on the " & sVarPre & " bus. "       & _
                 "After reading the last byte out of " & sRegPre & "RTB the stop condition " & _
                 "has to be set."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "InitSlaveMode"
  sDescription = "This function initializes the variables used for slave mode "    & _
                 "To check, if a data transfer is in progress, call the function "         & _
                 r.v(sVarPre & "_NAME_GetStatus") & "(). If the comparison "               & _
                 "if(" & r.v(sVarPre & "_NAME_GetStatus") & "() & (BB)) is "               & _
                 "'true' the bus is busy, that means, a start "                            & _
                 "condition has occured. If its 'false' a stop condition has occured, "    & _
                 "the bus is idle. "                                                       & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "Note:"                                                                   & vbcrlf & _
                 "There is no error handling defined. You have to take care of "           & _
                 "this by yourself. In the ISR " & r.v(sVarPre & "_NAME_Protocol")         & _
                 " you can fill in user specific code for the error handling."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "pointer to transmit buffer"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "*puwTransmitBuffer", "uword", sDescription)) Then Exit Function
    sDescription = "pointer to receive buffer"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "*puwReceiveBuffer", "uword", sDescription)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "DataTransfer"
  sDescription = "This is the transmit interrupt service routine for the " & sVarPre & ". " & _
               	 "It is called when the sending of data is terminated " & _
               	 "(XP0IR is set). " & vbcrlf & _
               	 TOOLTIP_ISR_USERCODE 

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 2)) Then Exit Function
 

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "Protocol"
  sDescription = "This is the transmit interrupt service routine for the " & sVarPre & ". " & _
               	 "It is called when the sending of data is terminated " & _
               	 "(XP1IR is set). " & vbcrlf & _
               	 TOOLTIP_ISR_USERCODE 

  sReturnValue = ""
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 2)) Then Exit Function
 

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "MasterTransmit"
  sDescription = "This function initializes the variables used for"                        & _
                 "(multi-)master transmit mode and starts the transmission."               & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "The following parameters are used :"                                     & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "uwDevice_Addr -    address of device to transmit to;"                    & vbcrlf & _
                 "uwSub_Addr    -    sub address of device"                                & vbcrlf & _
                 "                   (only if necessary);"                                 & vbcrlf & _
                 "                   has no effect if uwSubAddr_YN ="                      & vbcrlf & _
                 "                   " & r.v(sVarPre & "_PARA_WITHOUTSUBADDR")             & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "*uwTxBuffer   -    pointer to transmit buffer;"                          & vbcrlf & _
                 "uwBufferSize  -    amount of bytes to transmit;"                         & vbcrlf & _
                 "uwSubAddr_YN  -    with or without sub address"                          & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "The following definitions for uwSubAddr_YN are available:"               & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 r.v(sVarPre & "_PARA_WITHSUBADDR") & "    selects sub address mode"       & vbcrlf & _
                 r.v(sVarPre & "_PARA_WITHOUTSUBADDR") & " selects normal address mode"    & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "To use this function:"                                                   & vbcrlf & _
                 "A call to this function with the parameters described above "            & _
                 "initiates a data transfer from the master to the slave, "                & _
                 "addressed by uwDevice_Addr. *uwTxBuffer points to the first "            & _
                 "word to be transmitted (note, that only the low byte will be "           & _
                 "tranmitted), uwBufferSize indicates the amount of bytes to "             & _
                 "be transmitted."                                                         & vbcrlf & _
                 "To check, if a data transfer is in progress, call the function "         & _
                 r.v(sVarPre & "_NAME_GetStatus") & "(). If the comparison "               & _
                 "if(" & r.v(sVarPre & "_NAME_GetStatus") & "() & (BB)) is "               & _
                 "'true' the bus is busy, that means, a start "                            & _
                 "condition has occured. If its 'false' a stop condition has occured, "    & _
                 "the bus is idle. If uwI2CReady is set to 1 after data transfer "         & _
                 "is complete, the transmission was successfully finished. "               & _
                 "If uwI2CReady is set to 2, transmission failed."                         & vbcrlf & _
                 ""                                                                        & vbcrlf & _
                 "Note:"                                                                   & vbcrlf & _
                 "There is no error handling defined. You have to take care"               & _
                 "of this by yourself. In the ISR " & r.v(sVarPre & "_NAME_Protocol")      & _
                 "you can fill in user specific code for the error handling."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "device address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "uwDevice_Addr", "uword", sDescription)) Then Exit Function
    sDescription = "sub address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "uwSub_Addr", "uword", sDescription)) Then Exit Function
    sDescription = "pointer to transmit buffer"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para3", "*uwTxBuffer", "uword", sDescription)) Then Exit Function
    sDescription = "amount of bytes to transmit"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para4", "uwBufferSize", "uword", sDescription)) Then Exit Function
    sDescription = "with or without sub address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para5", "uwSubAddr_YN", "uword", sDescription)) Then Exit Function
 

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "MasterReceive"
  sDescription = "This function initializes the variables used for"                                   & _
                 "(multi-)master transmit mode and starts receiving."                                 & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "The following parameters are used :"                                                & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "uwDevice_Addr -   address of device to receive from;"                               & vbcrlf & _
                 "uwSub_Addr    -   sub address of device"                                            & vbcrlf & _
                 "                  (only if necessary);"                                             & vbcrlf & _
                 "                  has no effect if uwSubAddr_YN ="                                  & vbcrlf & _
                 "                  " & r.v(sVarPre & "_PARA_WITHOUTSubADDR")                         & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "*uwRxBuffer  -    pointer to receive buffer;"                                       & vbcrlf & _
                 "uwBufferSize -    amount of bytes to receive;"                                      & vbcrlf & _
                 "uwSubAddr_YN -    with or without sub address"                                      & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "The following definitions for uwSubAddr_YN are available:"                          & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 r.v(sVarPre & "_PARA_WITHSUBADDR") & "       selects sub address mode"               & vbcrlf & _
                 r.v(sVarPre & "_PARA_WITHOUTSUBADDR") & "    selects normal address mode"            & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "To use this function:"                                                              & vbcrlf & _
                 "A call to this function with the parameters described above "                       & _
                 "initiates a data transfer from the slave to the master, "                           & _
                 "addressed by uwDevice_Addr. *uwRxBuffer points to the first "                       & _
                 "byte to be received, uwBufferSize indicates the amount of "                         & _
                 "bytes to be received. "                                                             & _
                 "To check, if a data transfer is in progress, call the function "                    & _
                 r.v(sVarPre & "_NAME_GetStatus") & "(). If the comparison "                          & _
                 "if(" & r.v(sVarPre & "_NAME_GetStatus") & "() & (BB)) is "                          & _
                 "'true' the bus is busy, that means, a start "                                       & _
                 "condition has occured. If its 'false' a stop condition has occured, "               & _
                 "the bus is idle. If uwI2CReady is set to 1 after data transfer "                    & _
                 "is complete, the transmission was successfully finished. "                          & _
                 "If uwI2CReady is set to 2, transmission failed."                                    & vbcrlf & _
                 ""                                                                                   & vbcrlf & _
                 "Note:"                                                                              & vbcrlf & _
                 "There is no error handling defined. You have to take care of "                      & _
                 "this by yourself. In the ISR " & r.v(sVarPre & "_NAME_Protocol")                    & _
                 " you can fill in user specific code for the error handling."

  sReturnValue = "none"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "device address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "uwDevice_Addr", "uword", sDescription)) Then Exit Function
    sDescription = "sub address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "uwSub_Addr", "uword", sDescription)) Then Exit Function
    sDescription = "pointer to receive buffer"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para3", "*uwRxBuffer", "uword", sDescription)) Then Exit Function
    sDescription = "amount of bytes to receive"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para4", "uwBufferSize", "uword", sDescription)) Then Exit Function
    sDescription = "with or without sub address"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para5", "uwSubAddr_YN", "uword", sDescription)) Then Exit Function
 


 	If (Not func.Sort) Then Exit Function

  RefreshFunctionDescriptions = True
End Function


'*****************************************************************************
'Description:
'        For each parameter that should be used as a constant (on page "Parameters")  
'        a line "If (Not func.AddParameter .." must be insert in this function.
'
'        Note:
'        For each added parameter a project variable with the name 
'        "DUMMY_PARA_Parametername" must be exist in the *.vars file. 
'-----------------------------------------------------------------------------
'Parameters:
'        vIndex           parameter of the module which was added with AddModule
'        func             reference to the FunctionClass object
'        r                reference to the Registers object
'-----------------------------------------------------------------------------
'Returns:
'        True            on successfull operation
'        False           else
'*****************************************************************************
Public Function RefreshParameterDescriptions(vIndex As Variant, para As ParameterClass, r As ProjectData) As Boolean
  On Error Resume Next 

  RefreshParameterDescriptions = False

  Dim sDescription As String
  Dim sVarPre As String
  Dim sRegPre As String
  Dim sParaName As String
  Dim i As Integer

  sVarPre = "I2C" & vIndex
  sRegPre = "IC"


  ' for each parameter of this module the property AddParameter must be called
  '
  ' AddParameter(sParameterName As String, sParameterDescription As String) As Boolean
  '
  ' sParameterName         | String | parameter name as key (use the name of the variable 
  '                                   for the parameter name e.g. SSC_PARA_MODE) 
  ' sParameterDescription  | String | description of the parameter

  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " channel 0"
  sParaName = "CHANNEL0"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " channel 1"
  sParaName = "CHANNEL1"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " 7-bit addressing mode"
  sParaName = "ADR7"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " 10-bit addressing mode"
  sParaName = "ADR10"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " sub address mode"
  sParaName = "WITHSUBADDR"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
  '------------------------------------------------------------------------------------------------
  ' Description for I2C_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " normal address mode"
  sParaName = "WITHOUTSUBADDR"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
 	
 	If (Not para.Sort) Then Exit Function

  RefreshParameterDescriptions = True
End Function


'*****************************************************************************
'Description:
'          This function returns the module clock [MHz] of the 
'          ADC module depending on the configured modes
'-----------------------------------------------------------------------------
'Parameters:
'        r                reference to the Registers object
'        vIndex           ParameterValue
'-----------------------------------------------------------------------------
'Returns:
'      fcpu [MHz]
'
'*****************************************************************************
Function GetI2CModuleClock(r As ProjectData, vIndex As Variant) As Double
  On Error Resume Next
  GetI2CModuleClock = GetSystemClock(r) 
End Function



'*****************************************************************************
'Description:
'         This function updates the I2C baudrate.
'
'-----------------------------------------------------------------------------
'Parameters:
'        r                reference to the Registers object
'
'*****************************************************************************
Sub UpdateI2CBaudrate(r As ProjectData)
    On Error Resume Next
    Dim sVarPre As String
    Dim sRegPre As String
    Dim vBaudrate As Variant
    Dim vIndex As Variant

    sVarPre = "I2C"
    sRegPre = "IC"

    vBaudrate = r.d(sVarPre & "_Baudrate")
      If (vBaudrate < GetI2CMinBaudrate(r)) Then
        vBaudrate = GetI2CMinBaudrate(r)
      End If
      If (vBaudrate > GetI2CMaxBaudrate(r)) Then
        vBaudrate =  GetI2CMaxBaudrate(r)
      End If

    r.d(sVarPre & "_Baudrate") = vBaudrate
    r.l(sRegPre & "CFG_BRP") = GetI2CModuleClock(r, vIndex) * 1000000 / ( 4 * vBaudrate) - 1

End Sub

''*****************************************************************************
''Description:
''         This function updates the I2C baudrate.
''
''-----------------------------------------------------------------------------
''Parameters:
''        r                reference to the Registers object
''
''*****************************************************************************
'Sub UpdateI2CBaudrate(r As ProjectData)
'    On Error Resume Next
'    Dim sVarPre As String
'    Dim sRegPre As String
'    Dim vBaudrate As Variant
'    Dim vIndex As Variant
'
'    sVarPre = "I2C"
'    sRegPre = sVarPre & "_"
'
'    vBaudrate = r.d(sVarPre & "_Baudrate")
'      If (vBaudrate < GetI2CMinBaudrate(r)) Then
'        vBaudrate = GetI2CMinBaudrate(r)
'      End If
'      If (vBaudrate > GetI2CMaxBaudrate(r)) Then
'        vBaudrate =  GetI2CMaxBaudrate(r)
'      End If
'
'    r.d(sVarPre & "_Baudrate") = vBaudrate
'    r.l(sRegPre & "BUSCTRL_BRP") = GetI2CModuleClock(r, vIndex) * 1000000 / ( 4 * vBaudrate) - 1
'
'End Sub

'*****************************************************************************
'Description:
'          This function returns the real baudrate (in baud) of the 
'          I2C module depending on the module clock and the configured modes
'-----------------------------------------------------------------------------
'Parameters:
'        r                reference to the Registers object
'
'-----------------------------------------------------------------------------
'Returns:
'      the real-time baud rate [baud]
'
'*****************************************************************************
Function GetI2CRealBaudrate(r As ProjectData) As Double
    On Error Resume Next
    Dim sVarPre As String
    Dim sRegPre As String
    Dim v As String
    Dim vIndex As Variant
    sVarPre = "I2C" 
    sRegPre = "IC"

    GetI2CRealBaudrate = GetI2CModuleClock(r, vIndex) * 1000000 / (4 * (r.l(sRegPre & "CFG_BRP") + 1))


End Function

'*****************************************************************************
'Description:
'        This function sets the I2C to the default
'-----------------------------------------------------------------------------
'Parameters:
'        r              ProjectData
'        vIndex         module number
'-----------------------------------------------------------------------------
'Returns:
'     none
'*****************************************************************************
Sub SetI2CToDefault(r As ProjectData, vIndex As Variant)
    Dim sVarPre As String
    Dim sRegPre As String

    sVarPre = "I2C"
    sRegPre = "IC"

    If (r.v(sVarPre & "_Use_Ch_0") = 0) Then
        If (GetPinFunction(r, "SCL0") = 2) Then
            Call ReleaseAlternateOutputPin(r, "SCL0")
        End If
        If (GetPinFunction(r, "SDA0") = 2) Then
            Call ReleaseAlternateOutputPin(r, "SDA0")
        End If
        r.v(sRegPre & "CFG_SDASEL0") = 0
        r.v(sRegPre & "CFG_SCLSEL0") = 0
    End If
    
    If (r.v(sVarPre & "_Use_Ch_1") = 0) Then
        If (GetPinFunction(r, "SCL1") = 2) Then
            Call ReleaseAlternateOutputPin(r, "SCL1")
        End If
        If (GetPinFunction(r, "SDA1") = 2) Then
            Call ReleaseAlternateOutputPin(r, "SDA1")
        End If
        r.v(sRegPre & "CFG_SDASEL1") = 0
        r.v(sRegPre & "CFG_SCLSEL1") = 0
    End If

    If ( (r.v(sVarPre & "_Use_Ch_0") = 0) And (r.v(sVarPre & "_Use_Ch_1") = 0) ) Then
        r.v(sRegPre & "CON_MOD") = 0
        r.v(sVarPre & "_Ch_Connect") = 0
        Call DisableSRN(r, sVarPre, "XP0IC", "XP0IE", "DataTransfer")
        Call DisableSRN(r, sVarPre, "XP1IC", "XP1IE", "Protocol")
        r.v(sRegPre & "CON_AIRDIS") = 0
        r.v(sRegPre & "CON_M10") = 0
        r.sfr(sRegPre & "ADR") = 0
        r.v(sVarPre & "_USE_Init") = 0
        r.v(sVarPre & "_USE_MasterTransmit") = 0
        r.v(sVarPre & "_USE_MasterReceive") = 0
        r.v(sVarPre & "_USE_InitSlaveMode") = 0
    End If


End Sub

'*****************************************************************************
'Description:
'        This function check  the SYSCON3 register, whether the modul is disabled
'-----------------------------------------------------------------------------
'Parameters:
'        r               As ProjectData
'        vIndex          ParameterValue
'-----------------------------------------------------------------------------
'Returns:
'        True  -  if the modul is disabled
'        False -  else
'
'*****************************************************************************
Function IsModuleDisabled(r As ProjectData, vIndex As Variant) As Boolean

  IsModuleDisabled = False

  If (r.v("SYSCON3_" & GetI2CDisebleBitName(r, vIndex)) = 1) Then
    IsModuleDisabled = True
  End If

End Function

'*****************************************************************************
'Description:
'          This function returns the minimum baudrate (in baud) of the 
'          I2C module depending on the module clock and the configured modes
'-----------------------------------------------------------------------------
'Parameters:
'        r                reference to the Registers object
'
'-----------------------------------------------------------------------------
'Returns:
'      at a minimum possible baud rate [baud]
'
'*****************************************************************************
Function GetI2CMinBaudrate(r As ProjectData) As Double
  On Error Resume Next
  Dim sVarPre As String
  Dim v As String
  Dim vIndex As Variant
  sVarPre = "I2C" 

  GetI2CMinBaudrate = GetI2CModuleClock(r, vIndex) * 1000000 / (4 * (255 + 1))

End Function


'*****************************************************************************
'Description:
'          This function returns the maximum baudrate (in baud) of the 
'          I2C module depending on the module clock and the configured modes
'-----------------------------------------------------------------------------
'Parameters:
'        r                reference to the Registers object
'
'-----------------------------------------------------------------------------
'Returns:
'      at a maximum possible baud rate [baud]
'
'*****************************************************************************
Function GetI2CMaxBaudrate(r As ProjectData) As Double
  On Error Resume Next
  Dim sVarPre As String
  Dim v As String
  Dim vIndex As Variant
  sVarPre = "I2C" 

  If ((GetI2CModuleClock(r, vIndex) * 1000000 / 4) > 400000) Then 'if BR > 400 kbaud
      GetI2CMaxBaudrate = 400000
  Else
      GetI2CMaxBaudrate = GetI2CModuleClock(r, vIndex) * 1000000 / 4
  End If


End Function


'*****************************************************************************
'Description:
'        This function returns a formated disabled tooltip if the module
'        clock is disabled.
'-----------------------------------------------------------------------------
'Parameters:
'        r               reference to the ProjectData object
'        vIndex          parameter
'-----------------------------------------------------------------------------
'Returns:
'        Formated tooltip
'*****************************************************************************
Function GetTooltipModuleDisabled(r As ProjectData, vIndex As Variant) As String
  On Error Resume Next
  Dim sVarPre As String

  sVarPre = "I2C" & vIndex
  
  GetTooltipModuleDisabled = ""            
  GetTooltipModuleDisabled =  GetTooltipModuleDisabled & FormatDisabledToolTip("the " & sVarPre & " module is disabled")
End Function

'*****************************************************************************
'Description:
'        This function returns the disable bit name of SYSCON3 register (e.g SSCDIS).
'-----------------------------------------------------------------------------
'Parameters:
'        r               reference to the ProjectData object
'        vIndex          ParameterValue
'
'-----------------------------------------------------------------------------
'Returns:
'       disable bit name
'*****************************************************************************
Function GetI2CDisebleBitName(r As ProjectData, vIndex As Variant) As String
    On Error Resume Next

    If (r.Regs.BitFind("SYSCON3_I2CDIS") = True) Then
        GetI2CDisebleBitName = "I2CDIS"
    Else
        GetI2CDisebleBitName = ""
    End If


End Function


