doc: clarifying comment behavior in framework files, #268

Author: sylefeb

learn-silice/Documentation.md

@@ -3,7 +3,7 @@
 
 This is the Silice main documentation.
 
-When designing with Silice your code describes circuits. If not done already, I recommended to [watch the introductory video](https://www.youtube.com/watch?v=_OhxEY72qxI) (youtube) to get more familiar with this notion and what it entails. The video is slightly outdated in terms of what Silice can do, but still useful when getting started.
+When designing with Silice your code describes circuits. If not done already, I recommended to [watch the introductory video](https://www.youtube.com/watch?v=_OhxEY72qxI) (youtube) to get more familiar with this notion and what it entails. The video is slightly outdated in terms of what Silice can do, but still useful when getting started. Another more recent video that focuses on graphics applications and showcases new capabilities is [here](https://www.youtube.com/watch?v=XycwTFPDZ6w).
 
 ## Table of content
 
@@ -2420,6 +2420,57 @@ For practical usage examples please refer to the [*Getting started* guide](../Ge
 
 New frameworks for additional boards [can be easily created](../frameworks/boards/README.md).
 
+## Lua pre-processor in frameworks
+
+Frameworks can 'escape' Verilog to add [Lua preprocessor](#lua-preprocessor) instructions.
+Beware that this happens before the Verilog file is parsed, so the Verilog syntax
+does not influence these pre-processor lines. This is particularly the case
+for comments.
+
+For instance, consider the following framework file:
+
+``` verilog
+// This is a Verilog framework 'glue' file
+
+// Next some Verilog defines, these are only seen by the FPGA/ASIC/simulation
+// toolchain in the final compiled file.
+`define ICEBREAKER 1
+`define ICE40 1
+`default_nettype none
+// Next some lines escaping to the Lua preprocessor, these lines are visible
+// to Silice at compile time, but are oblivious to the surrounding Verilog code.
+$$ICEBREAKER  = 1
+$$ICE40       = 1
+$$HARDWARE    = 1
+// For instance consider the following
+/*
+$$VAR1 = 1
+*/
+// The comment around the $$ escaped line is invisible to Silice, so VAR1 is
+// indeed defined in Silice!
+// This is also true of something like this:
+`ifdef NOT_DEFINED
+$$VAR2 = 1
+`endif
+// The variable VAR2 will be defined as seen by the preprocessor, even though
+// NOT_DEFINED is not defined in the Verilog part. Again the Lua preprocessor
+// executes before Verilog is parsed by the toolchain.
+
+// Here are several possible ways to resolve this:
+// 1) Use a Lua comment
+$$ -- VAR3 = 3
+// ^^ this is a comment in the preprocessor language (Lua), the line is ignored
+// 2) Use preprocessor conditions to disable multiple lines
+$$ if false then
+$$   VAR4 = 4
+$$   VAR5 = 5
+$$ end
+// ^^ here the definition of VAR3 is skipped
+// 3) Use a single line comment, this is properly taken into account by the
+//    framework parser, for convenience.
+// $$ VAR6 = 6
+```
+
 ## VGA and OLED simulation
 
 The Silice verilator framework supports VGA and OLED display out of the box. For instance see the [VGA demos project](../projects/vga_demo/README.md).

src/SiliceCompiler.cpp

@@ -306,6 +306,15 @@ void SiliceCompiler::gatherUnitBody(AutoPtr<Algorithm> unit, antlr4::tree::Parse
 
 // -------------------------------------------------
 
+std::string ltrim(const std::string s)
+{
+  std::string r = s;
+  r.erase(r.begin(),
+    std::find_if(r.begin(), r.end(), [](unsigned char c) { return !std::isspace(c); }
+  ));
+  return r;
+}
+
 void SiliceCompiler::prepareFramework(std::string fframework, std::string& _lpp, std::string& _verilog)
 {
   // if we don't have a framework (as for the formal board),
@@ -322,6 +331,7 @@ void SiliceCompiler::prepareFramework(std::string fframework, std::string& _lpp,
   }
   std::string line;
   while (std::getline(infile, line)) {
+    line = ltrim(line);
     if (line.substr(0, 2) == "$$") {
       _lpp += line.substr(2) + "\n";
     } else {

tests/comments1.si

@@ -0,0 +1,31 @@
+
+unit main(output uint8 leds)
+{
+
+  // This is a comment
+  /*
+    This is a comment
+  */
+  
+  $$ VAR1 = 1 -- this is a comment in preprocessor escape (Lua language)
+  
+  // $$ VAR2 = 2
+  // ^^ ignored as commented in Silice source
+
+  /*
+  $$ VAR3 = 3
+  ^^ ignored as commented in Silice source
+  */
+
+  $$ -- VAR4 = 4   => ignored as commented in preprocessor (leading --)
+
+  $$ print('VAR1 = ' .. VAR1)
+  $$ if VAR2 then print('VAR2 defined') else print('VAR2 NOT defined') end
+  $$ if VAR3 then print('VAR3 defined') else print('VAR3 NOT defined') end
+  $$ if VAR4 then print('VAR4 defined') else print('VAR4 NOT defined') end
+
+  always {
+    __finish();
+  }
+
+}