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


Option Explicit

'*****************************************************************************
' Module:
'        ADC
'-----------------------------------------------------------------------------
' Description:
'        This module contains all functions that are used in the 
'        ADC dialog script and in the ADC codegenerator script.
'
'-----------------------------------------------------------------------------
' History:
'                 
'        Rev. Author         Date        Description
'        ---------------------------------------------------------------------
'        1.0   ahe         14.06.00     final version
'
'        ---------------------------------------------------------------------
'        2.0   ahe         20.07.00     final version for C161PI
'                                       - reduzierung von Ch's von 24 auf 4
'
'        ---------------------------------------------------------------------
'        3.0   ahe         07.08.00     final version for C161CS/JC/JI
'                                       - only AN0..AN7 and AN12..AN15
'              ahe         23.02.01     - changes ConfConv function description
'
'*****************************************************************************


'*****************************************************************************
' Constants
'*****************************************************************************

'*****************************************************************************
'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 
'        "ADC_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 sFctName As String

  sVarPre = "ADC" & vIndex

  ' 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 ADC_NAME_Init
  '------------------------------------------------------------------------------------------------
  sDescription = GetGeneralInitDescription(sVarPre)
  
  sReturnValue = "None" 
  
  If (Not func.AddFunction(sVarPre & "_NAME_Init", "void", sDescription, sReturnValue, 1)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "StartConv"
  sDescription = "This macro starts the A/D conversion."

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ConfConv"
  sDescription = "This function configures a new A/D conversion. In fixed channel " & _
                 "single conversion mode (" & r.v(sVarPre & "_PARA_FIXED") & ") the forwarded channel is " & _
                 "converted once. In fixed channel continuous conversion mode " & _
                 "(" & r.v(sVarPre & "_PARA_FIXED_CONTI") & ") the forwarded channel is converted " & _
                 "continuously. In auto scan single conversion mode (" & r.v(sVarPre & "_PARA_SCAN") & ") a " & _
                 "sequence beginning with the forwarded channel and ending " & _
                 "with channel 0 is converted. In auto scan continuous " & _
                 "conversion mode (" & r.v(sVarPre & "_PARA_SCAN_CONTI") & ") the sequence is converted " & _
                 "continuously. To start the conversion it is necessary to " & _
                 "call " & r.v(sVarPre & "_NAME_StartConv") & "." & vbcrlf & _
                 "Note: " & vbcrlf & _
                 "While a conversion is in progress, the mode and the channel " & _
                 "may be changed. The new mode will be evaluated after the " & _
                 "current conversion.The new channel will be evaluated after " & _
                 "the current conversion (fixed channel modes) or after the " & _
                 "current conversion sequence (auto scan modes). " & _
                 " " & _
                 "The following constants are available for ubMode: " & vbcrlf & _
                 "" & r.v(sVarPre & "_PARA_FIXED") & " " & vbcrlf & _
                 "" & r.v(sVarPre & "_PARA_FIXED_CONTI") & " " & vbcrlf & _
                 "" & r.v(sVarPre & "_PARA_SCAN") & " " & vbcrlf & _
                 "" & r.v(sVarPre & "_PARA_SCAN_CONTI") & " " & vbcrlf & _
                 " " & vbcrlf & _
                 "The following constants are available for ubChannel: " & vbcrlf & _
                 r.v(sVarPre & "_PARA_ANA_0") & " .. " & r.v(sVarPre & "_PARA_ANA_7") & " and " & vbcrlf & _
                 r.v(sVarPre & "_PARA_ANA_12") & " .. " & r.v(sVarPre & "_PARA_ANA_15") & " (see @Defines in header file) "

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "Conversion mode"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "ubMode", "ubyte", sDescription)) Then Exit Function
    sDescription = "Channel number"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para2", "ubChannel", "ubyte", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "StopConv"
  sDescription = "This macro stops a continuous A/D conversion. The last conversion or sequence is terminated correctly."

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ConvReady"
  sDescription = "This macro detects the end of a conversion (ADCIR). " & _
                 "If the conversion is completed, the ADDAT register " & _
                 "can be read with the function " & r.v(sVarPre & "_NAME_ReadConv") & "."

  sReturnValue = "1 if conversion is completed, else 0"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ReadConv"
  sDescription = "This function returns the result of a conversion. " & _
                 "This function must be called after each conversion. " & _
                 "The lower 10 bits contain the conversion result " & _
                 "while the upper 4 bits identify the converted " & _
                 "analog channel. "

  sReturnValue = "Conversion result"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "uword", sDescription, sReturnValue, 1)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "OverWrite"
  sDescription = "This function checks if the last conversion result has " & _
                 "overwritten a previous value in register ADDAT (present" & _
                 "in standard mode)."

  sReturnValue = "1 the last conversion result was overwritten, else 0"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "ubyte", sDescription, sReturnValue, 1)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "Busy"
  sDescription = "This macro checks if an A/D conversion is active or not.  " & _
                 "If a task has to wait for the result of an A/D conversion " & _
                 "(result is read in the ISR), it can find with this macro, " & _
                 "when the " & sVarPre & " is ready. "

  sReturnValue = "Returns a 1 if AD converter is active, else 0"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "Conv"
  sDescription = "This is the interrupt service routine for the " & sVarPre & ". " & _
                 "It is called at the end of each conversion. The user " & _
                 "obtains the conversion result by calling the function " & _
                 r.v(sVarPre & "_NAME_ReadConv") & "."

                 sDescription = sDescription & vbcrlf & TOOLTIP_ISR_USERCODE

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 2)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "Error"
  sDescription = "This is the interrupt service routine for the overwrite error " & _
                 "of the " & sVarPre & " (in standard mode) - the last measurement result " & _
                 "was overwritten - , or the ISR for the end of an injected " & _
                 "conversion - the result of the injected conversion has been" & _
                 "written to ADDAT2. An overrun is not possible in channel " & _
                 "injection mode; in this case the AD measurement is stopped. " & _
                 "To get the injected conversion result the user can call the " & _
                 "function " & r.v(sVarPre & "_NAME_ReadInject") & "."

                 sDescription = sDescription & vbcrlf & TOOLTIP_ISR_USERCODE

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "void", sDescription, sReturnValue, 2)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "InjectChan"
  sDescription = "This function loads the parameter ubChannel into the ADDAT2 " & _
                 "register. During the next injected conversion this channel " & _
                 "is converted. This conversion is initiated by the function " & _
                 r.v(sVarPre & "_NAME_StartInject") & ". " & _
                 "If an injected conversion is active, the channel may not " & _
                 "be changed. " & _
                 " " & vbcrlf & _
                 "The following constants are available for ubChannel: " & vbcrlf & _
                 r.v(sVarPre & "_PARA_ANA_0") & " .. " & r.v(sVarPre & "_PARA_ANA_7") & " and " & vbcrlf & _
                 r.v(sVarPre & "_PARA_ANA_12") & " .. " & r.v(sVarPre & "_PARA_ANA_15") & " (see @Defines in header file) "

  sReturnValue = "0 if channel has not been switched (injec. conv. active), else 1"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "ubyte", sDescription, sReturnValue, 1)) Then Exit Function
    sDescription = "Input channel for the channel injection mode"
    If (Not func.AddParameter(sVarPre & "_NAME_" & sFctName & "_Para1", "ubChannel", "ubyte", sDescription)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "StartInject"
  sDescription = "This macro starts an injected A/D conversion."

  sReturnValue = "None"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "ReadInject"
  sDescription = "This function returns the result of the last injected " & _
                 "conversion. The result is in register ADDAT2, if the " & _
                 "interrupt request flag ADEIR has been set. " & _
                 "The lower 10 bits contain the injected conversion result " & _
                 "and the upper 4 bits identify the converted analog " & _
                 "channel."

  sReturnValue = "Injected conversion result"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "uword", sDescription, sReturnValue, 1)) Then Exit Function
 
  '------------------------------------------------------------------------------------------------
  ' Description for ADC_NAME_...
  '------------------------------------------------------------------------------------------------
  sFctName = "InjectReady"
  sDescription = "This macro detects the end of a injected conversion. " & _
                 "If the injected conversion is completed, the ADDAT2" & _
                 "register can be read with the function " & r.v(sVarPre & "_NAME_ReadInject") & "."

  sReturnValue = "Returns a 1 if injected conversion is completed, else 0"
  If (Not func.AddFunction(sVarPre & "_NAME_" & sFctName, "", sDescription, sReturnValue, 0)) 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 = "ADC" & vIndex
  sRegPre = sVarPre & "_"


  ' 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 DUMMY_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " fixed channel single conversion mode"
  sParaName = "FIXED"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for DUMMY_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " fixed channel continuous conversion mode"
  sParaName = "FIXED_CONTI"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for DUMMY_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " auto scan single conversion mode"
  sParaName = "SCAN"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function

  '------------------------------------------------------------------------------------------------
  ' Description for DUMMY_PARA_xx
  '------------------------------------------------------------------------------------------------
  sDescription = "This parameter identifies " & sVarPre & " auto scan continuous conversion mode"
  sParaName = "SCAN_CONTI"
  If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function


  For i = 0 To 7
      '------------------------------------------------------------------------------------------------
      ' Description for DUMMY_PARA_xx
      '------------------------------------------------------------------------------------------------
      sDescription = "This parameter identifies " & sVarPre & " analog channel " & i
      sParaName = "ANA_" & i
      If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
  Next i
  
  For i = 12 To 15
      '------------------------------------------------------------------------------------------------
      ' Description for DUMMY_PARA_xx
      '------------------------------------------------------------------------------------------------
      sDescription = "This parameter identifies " & sVarPre & " analog channel " & i
      sParaName = "ANA_" & i
      If (Not para.AddParameter(sVarPre & "_PARA_" & sParaName, sDescription)) Then Exit Function
  Next i
  
 	
 	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:
'      GetADCSystemClock [MHz]
'
'*****************************************************************************
Function GetADCModuleClock(r As ProjectData, vIndex As Variant) As Double
  On Error Resume Next
  GetADCModuleClock = GetSystemClock(r) 
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 = "ADC" & 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 GetADCDisebleBitName(r As ProjectData, vIndex As Variant) As String
    On Error Resume Next

    If (r.Regs.BitFind("SYSCON3_ADCDIS") = True) Then
        GetADCDisebleBitName = "ADCDIS"
    Else
        GetADCDisebleBitName = ""
    End If


End Function


'*****************************************************************************
'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_" & GetADCDisebleBitName(r, vIndex)) = 1) Then
    IsModuleDisabled = True
  End If

End Function
