Add doc comments for some CoRA changes under dmt

dmt/B_mappers/simulink_B_mapper.py

@@ -454,6 +454,7 @@ class SimulinkGlueGenerator(SynchronousToolGlueGenerator):
         self.C_SourceFile.write("    if (!initialized) {\n")
         self.C_SourceFile.write("        initialized = 1;\n")
         self.C_SourceFile.write("        %s_initialize(1);\n" % self.g_FVname)
+        # If there are HW(FPGA) configurations defined, initialize also the HW side (the device driver: <self.g_FVname>_Simulink.vhdl.c).
         if sp._fpgaConfigurations is not '':
             self.C_SourceFile.write("        init_%s_Brave_Fpga();\n" % maybeFVname)
         self.C_SourceFile.write("    }\n")

dmt/B_mappers/synchronousTool.py

@@ -37,8 +37,15 @@ TSource = TypeVar('TSource')
 TDestin = TypeVar('TDestin')
 
 brave_seen = {}
+# Add suffix to generated FPGA device driver's (<PI name>_<Language>.vhdl.c) functions to avoid multiple definition errors (conflict with "vm_if")
 fpgaSuffix = ''
+# Add a different suffix to the dispatcher C function (part of device driver)
+# Dispatcher <Function Block name>_<PI name><dispatcherSuffix> will delegate to one or the other side (SW or HW)
+# If delegation is to HW, then <Function Block name>_<PI name><fpgaSuffix> will be called
 dispatcherSuffix = "_Brave_Dispatch"
+# FPGA/HW device driver (<PI name>_<Language>.vhdl.c) is being generated (also) when Function Block will exist both as SW and HW, that is, when
+# 1) language defined is C or Simulink but on the autogen pass is "seen" as VHDL (so that respective B-mapper is invoked),
+# and 2) there are FPGA configurations defined (default is False)
 genHwDevDrv = False
 
 class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
@@ -109,12 +116,17 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
                   outputDir: str,
                   maybeFVname: str,
                   useOSS: bool) -> None:
+        # FPGA/HW device driver is being generated (also) when Function Block will exist both as SW and HW, that is, when
+        # 1) language defined is C or Simulink but on this autogen pass is "seen" as VHDL (so that respective B-mapper is invoked),
+        # and 2) there are FPGA configurations defined
         global genHwDevDrv
+        # Add suffix to generated FPGA device driver's functions to avoid multiple definition errors (conflict with "vm_if")
         global fpgaSuffix
         genHwDevDrv = subProgram._fpgaConfigurations is not '' and ((subProgramImplementation.lower() == "c" or subProgramImplementation.lower() == "simulink") and modelingLanguage == "vhdl");
         if genHwDevDrv:
             fpgaSuffix = "_Brave_Fpga"
         else:
+            # To avoid code duplication, use suffix anyway but as an empty string when not to be applied
             fpgaSuffix = ''
         
         if modelingLanguage == "QGenAda":
@@ -525,7 +537,6 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
         self.Common(nodeTypename, node, subProgram, subProgramImplementation, param, leafTypeDict, names)
 
     def OnShutdown(self, modelingLanguage: str, asnFile: str, sp: ApLevelContainer, subProgramImplementation: str, maybeFVname: str) -> None:
-        # Check if Function Block will exist both as SW and HW
         global genHwDevDrv
         global fpgaSuffix
         global dispatcherSuffix
@@ -591,7 +602,6 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
                 self.CleanNameAsADAWants(sp._id + "_" + subProgramImplementation + "_wrapper"))
 
         else:
-            # Check if Function Block will exist both as SW and HW. If yes append suffix to avoid multiple definition errors.
             if genHwDevDrv:
                 if maybeFVname not in brave_seen:
                     brave_seen[maybeFVname] = 'no_init_yet';
@@ -622,6 +632,9 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
             self.C_HeaderFile.write(");\n")
             
             # Check if Function Block will exist both as SW and HW. If yes generate dispatcher function (to delegate to SW or HW).
+            # Dispatcher <Function Block name>_<PI name><dispatcherSuffix> is part of the FPGA device driver <PI name>_<Language>.vhdl.h/c
+            # Dispatcher can return: 0 (successfully delegated to HW), 1 (delegated to SW), 2 (unsuccessfully delegated to HW)
+            # Here being added to the .h file
             if genHwDevDrv:
                 if maybeFVname != "":
                     self.C_HeaderFile.write("int %s_%s%s(" % (self.CleanNameAsADAWants(maybeFVname), self.CleanNameAsADAWants(sp._id), dispatcherSuffix))
@@ -673,6 +686,15 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
                     self.C_SourceFile.write('void *p' + self.CleanNameAsToolWants(param._id) + ', size_t *pSize_' + self.CleanNameAsToolWants(param._id))
             self.C_SourceFile.write(")\n{\n")
 
+            # Call Dispatcher function
+            # Dispatcher will delegate to one or the other side (SW or HW) depending on whether the value of the global variable storing the current
+            # configuration equals one of those configurations defined for the target Function Block (in IV field listing the FPGA configurations)
+            # Mechanism is as follows:
+            # 1) SW side glue <PI name>_<Language>.<Language>.h/c calls HW side glue (device driver) <PI name>_<Language>.vhdl.h/c
+            #   specifically <Function Block name>_<PI name> function calls the Dispatcher <Function Block name>_<PI name><dispatcherSuffix>
+            # 2) Dispatcher in HW side delegates back to SW side (when returning 1 or 2) or to FPGA (and returns 0)
+            # 3) If successfully delegated to HW (returning 0), SW side returns immediately so to avoid calling up SW side as well
+            #   Otherwise execution continues up trough "normal" SW side calling
             if sp._fpgaConfigurations is not '' and subProgramImplementation.lower() == "simulink" and modelingLanguage != "vhdl":
                 self.C_SourceFile.write('    // Calling Brave VHDL dispatcher function\n')
                 self.C_SourceFile.write('    if (0 == %s_%s%s (' % \
@@ -743,6 +765,9 @@ class SynchronousToolGlueGeneratorGeneric(Generic[TSource, TDestin]):
             self.C_SourceFile.write("}\n\n")
 
             # Check if Function Block will exist both as SW and HW. If yes generate dispatcher function (to delegate to SW or HW).
+            # Dispatcher <Function Block name>_<PI name><dispatcherSuffix> is part of the FPGA device driver <PI name>_<Language>.vhdl.h/c
+            # Dispatcher can return: 0 (successfully delegated to HW), 1 (delegated to SW), 2 (unsuccessfully delegated to HW)
+            # Here being added to the .c file
             if genHwDevDrv:
                 if maybeFVname != "":
                     self.C_SourceFile.write("int %s_%s%s(" % (self.CleanNameAsADAWants(maybeFVname), self.CleanNameAsADAWants(sp._id), dispatcherSuffix))

dmt/aadl2glueC.py

@@ -391,10 +391,13 @@ def ProcessCustomBackends(
         else:
             panic("Unexpected call of getCustomBackends...")  # pragma: no cover
 
+    # Add call to the VHDL B-mapper also for C and Simulink functions (x[2]) with FPGA configuration(s) defined (x[4])
     for si in [x for x in SystemsAndImplementations if x[2] is not None and (x[2].lower() in ["gui_ri", "gui_pi", "vhdl"] or ((x[2].lower() == "c" or x[2].lower() == "simulink") and len(x)>4 and x[4] is not ''))]:
         # We do, start the work
         spName, sp_impl, lang, maybeFVname = si[0], si[1], si[2], si[3]
+        # Add call to the VHDL B-mapper also for C and Simulink functions (si[2]) with FPGA configuration(s) defined (si[4])
         if (si[2].lower() == "c" or si[2].lower() == "simulink") and len(si)>4 and si[4] is not '':
+            # pretend its VHDL
             lang = "vhdl"
         sp = commonPy.aadlAST.g_apLevelContainers[spName]
         if len(sp._params) == 0:

dmt/commonPy2/AadlParser.py

@@ -1251,6 +1251,7 @@ class Parser(antlr.LLkParser):
             if not g_apLevelContainers.has_key(typeid.getText()):
                panic("Line %d: Subprogram (%s) must first be declared before it is implemented" % (typeid.getLine(), typeid.getText()))
             sp = g_apLevelContainers[typeid.getText()]
+            # Add field for FPGA configurations
             g_subProgramImplementations.append([typeid.getText(), defid.getText(), sp._language, "", sp._fpgaConfigurations])
         la1 = self.LA(1)
         if False:
@@ -1330,6 +1331,7 @@ class Parser(antlr.LLkParser):
                        stripQuotes = assoc._value.replace("\"", "")
                        #sp.SetLanguage(stripQuotes) 
                        g_subProgramImplementations[-1][3] = stripQuotes
+                   # Assign defined FPGA configurations
                    if assoc._name[-19:].lower() == "fpga_configurations":
                        stripQuotes = assoc._value.replace("\"", "")
                        g_subProgramImplementations[-1][4] = stripQuotes

dmt/commonPy2/aadlAST.py

@@ -151,7 +151,7 @@ class ApLevelContainer:
         self._calls = []
         self._params = []
         self._connections = []
-        self._fpgaConfigurations = ''
+        self._fpgaConfigurations = '' # The configuration(s)/"mode(s)" for which the Function's HW implementation shall apply (execution in FPGA)
         self._language = None
 
     def AddCalledAPLC(self, idAPLC):
@@ -170,6 +170,7 @@ class ApLevelContainer:
     def SetLanguage(self, language):
         self._language = language
 
+    # Assign FPGA configurations
     def SetFPGAConfigurations(self, fpgaConfigurations):
         self._fpgaConfigurations = fpgaConfigurations