Updated logging documentation.

docs/logging/additional_subprograms.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span><span class="n">ui</span> <span class="o">=</span> <span class="n">VUnit</span><span class="o">.</span><span class="n">from_argv</span><span class="p">()</span>
+<span class="n">ui</span><span class="o">.</span><span class="n">add_vhdl_builtins</span><span class="p">()</span>
+<span class="n">ui</span><span class="o">.</span><span class="n">enable_location_preprocessing</span><span class="p">(</span><span class="n">additional_subprograms</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;my_convenience_procedure&quot;</span><span class="p">])</span>
+</pre></div>

docs/logging/another_convenience_procedure.html

@@ -0,0 +1,11 @@
+<div class="highlight"><pre><span></span><span class="k">procedure</span><span class="w"> </span><span class="n">my_convenience_procedure</span><span class="p">(</span>
+<span class="w">  </span><span class="c1">-- Custom parameters ...</span>
+
+<span class="w">  </span><span class="n">line_num</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="kt">natural</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
+<span class="w">  </span><span class="n">file_name</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">)</span><span class="w"> </span><span class="k">is</span>
+<span class="k">begin</span>
+<span class="w">  </span><span class="c1">-- Some code ...</span>
+<span class="w">  </span><span class="n">info</span><span class="p">(</span><span class="s">&quot;Some message&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">line_num</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">line_num</span><span class="p">,</span><span class="w"> </span><span class="n">file_name</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">file_name</span><span class="p">);</span>
+<span class="w">  </span><span class="c1">-- Some code ...</span>
+<span class="k">end</span><span class="w"> </span><span class="k">procedure</span><span class="w"> </span><span class="nc">my_convenience_procedure</span><span class="p">;</span>
+</pre></div>

docs/logging/conditional_log.html

@@ -0,0 +1,6 @@
+<div class="highlight"><pre><span></span><span class="n">warning_if</span><span class="p">(</span><span class="n">True</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;A warning happened&quot;</span><span class="p">);</span>
+<span class="n">warning_if</span><span class="p">(</span><span class="n">False</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;A warning did not happen&quot;</span><span class="p">);</span>
+
+<span class="c1">-- There are also variants for error and failure as well as with</span>
+<span class="c1">-- non-default logger argument.</span>
+</pre></div>

docs/logging/convenience_procedure.html

@@ -0,0 +1,9 @@
+<div class="highlight"><pre><span></span><span class="k">procedure</span><span class="w"> </span><span class="n">my_convenience_procedure</span><span class="p">(</span>
+<span class="w">  </span><span class="c1">-- Parameters ...</span>
+<span class="p">)</span><span class="w"> </span><span class="k">is</span>
+<span class="k">begin</span>
+<span class="w">  </span><span class="c1">-- Some code ...</span>
+<span class="w">  </span><span class="n">info</span><span class="p">(</span><span class="s">&quot;Some message&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">path_offset</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
+<span class="w">  </span><span class="c1">-- Some code ...</span>
+<span class="k">end</span><span class="w"> </span><span class="k">procedure</span><span class="w"> </span><span class="nc">my_convenience_procedure</span><span class="p">;</span>
+</pre></div>

docs/logging/custom_log_level.html

@@ -0,0 +1,2 @@
+<div class="highlight"><pre><span></span><span class="k">constant</span><span class="w"> </span><span class="n">license_info</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">log_level_t</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">new_log_level</span><span class="p">(</span><span class="s">&quot;license&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fg</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">red</span><span class="p">,</span><span class="w"> </span><span class="n">bg</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">yellow</span><span class="p">,</span><span class="w"> </span><span class="n">style</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">bright</span><span class="p">);</span>
+</pre></div>

docs/logging/disabled_log.html

@@ -0,0 +1,3 @@
+<div class="highlight"><pre><span></span><span class="c1">-- Irrelevant warning</span>
+<span class="n">disable</span><span class="p">(</span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;memory_ip:timing_check&quot;</span><span class="p">),</span><span class="w"> </span><span class="n">warning</span><span class="p">);</span>
+</pre></div>

docs/logging/fix_decimals_log.html

@@ -0,0 +1,2 @@
+<div class="highlight" style="background: #002b36; color: #eee8d5;"><pre style="line-height: 125%; background: #002b36; color: #eee8d5;"><span style="color: #2aa198; ">123.45 ns</span> - <span style="font_weight: bold; color: #eee8d5; ">default</span>              -    <span style="font_weight: bold; color: #008000; ">PASS</span> - Passes are green
+</pre></div>

docs/logging/full_time_resolution_log.html

@@ -0,0 +1,2 @@
+<div class="highlight" style="background: #002b36; color: #eee8d5;"><pre style="line-height: 125%; background: #002b36; color: #eee8d5;"><span style="color: #2aa198; ">0.123456 us</span> - <span style="font_weight: bold; color: #eee8d5; ">check</span>                - <span style="font_weight: bold; color: #eee8d5; background: #cb4b16; ">FAILURE</span> - Failures are even more red
+</pre></div>

docs/logging/location_preprocessing.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span><span class="n">ui</span> <span class="o">=</span> <span class="n">VUnit</span><span class="o">.</span><span class="n">from_argv</span><span class="p">()</span>
+<span class="n">ui</span><span class="o">.</span><span class="n">add_vhdl_builtins</span><span class="p">()</span>
+<span class="n">ui</span><span class="o">.</span><span class="n">enable_location_preprocessing</span><span class="p">()</span>
+</pre></div>

docs/logging/log_call.html

@@ -0,0 +1,2 @@
+<div class="highlight"><pre><span></span><span class="n">info</span><span class="p">(</span><span class="s">&quot;Hello world&quot;</span><span class="p">);</span>
+</pre></div>

docs/logging/log_call_with_custom_level.html

@@ -0,0 +1,3 @@
+<div class="highlight"><pre><span></span><span class="n">log</span><span class="p">(</span><span class="s">&quot;Mozilla Public License, v. 2.0.&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">license_info</span><span class="p">);</span>
+<span class="n">log</span><span class="p">(</span><span class="n">my_logger</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Mozilla Public License, v. 2.0.&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">license_info</span><span class="p">);</span>
+</pre></div>

docs/logging/log_call_with_logger.html

@@ -0,0 +1,2 @@
+<div class="highlight"><pre><span></span><span class="n">info</span><span class="p">(</span><span class="n">my_logger</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Hello world&quot;</span><span class="p">);</span>
+</pre></div>

docs/logging/log_location_log.html

@@ -0,0 +1,2 @@
+<div class="highlight" style="background: #002b36; color: #eee8d5;"><pre style="line-height: 125%; background: #002b36; color: #eee8d5;"><span style="color: #2aa198; ">1.260 us</span> - <span style="font_weight: bold; color: #eee8d5; ">check</span>                -   <span style="font_weight: bold; color: #cb4b16; ">ERROR</span> - Equality check failed for packet length - Got 15. Expected 16. (receiver.vhd:73)
+</pre></div>

docs/logging/log_time_unit_log.html

@@ -0,0 +1,2 @@
+<div class="highlight" style="background: #002b36; color: #eee8d5;"><pre style="line-height: 125%; background: #002b36; color: #eee8d5;"><span style="color: #2aa198; ">123.456 ns</span> - <span style="font_weight: bold; color: #eee8d5; ">check</span>                -   <span style="font_weight: bold; color: #cb4b16; ">ERROR</span> - Errors are red
+</pre></div>

docs/logging/log_visibility.html

@@ -0,0 +1,12 @@
+<div class="highlight"><pre><span></span><span class="c1">-- Disable all logging to the display.</span>
+<span class="n">hide_all</span><span class="p">(</span><span class="n">display_handler</span><span class="p">);</span>
+
+<span class="c1">-- Show debug log level of system0 logger to the display</span>
+<span class="n">show</span><span class="p">(</span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;system0&quot;</span><span class="p">),</span><span class="w"> </span><span class="n">display_handler</span><span class="p">,</span><span class="w"> </span><span class="n">debug</span><span class="p">);</span>
+
+<span class="c1">-- Show all logging from the uart module in system0 to the display</span>
+<span class="n">show_all</span><span class="p">(</span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;system0:uart&quot;</span><span class="p">),</span><span class="w"> </span><span class="n">display_handler</span><span class="p">);</span>
+
+<span class="c1">-- Hide all debug output to display handler</span>
+<span class="n">hide</span><span class="p">(</span><span class="n">display_handler</span><span class="p">,</span><span class="w"> </span><span class="n">debug</span><span class="p">);</span>
+</pre></div>

docs/logging/logger_declaration.html

@@ -0,0 +1,2 @@
+<div class="highlight"><pre><span></span><span class="k">constant</span><span class="w"> </span><span class="n">my_logger</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">logger_t</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;system0:uart0&quot;</span><span class="p">);</span>
+</pre></div>

docs/logging/logger_from_id.html

@@ -0,0 +1,3 @@
+<div class="highlight"><pre><span></span><span class="k">constant</span><span class="w"> </span><span class="n">my_id</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">id_t</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">get_id</span><span class="p">(</span><span class="s">&quot;system0:uart0&quot;</span><span class="p">);</span>
+<span class="k">constant</span><span class="w"> </span><span class="n">my_logger</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">logger_t</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">get_logger</span><span class="p">(</span><span class="n">my_id</span><span class="p">);</span>
+</pre></div>

docs/logging/mock_queue_length.html

@@ -0,0 +1,9 @@
+<div class="highlight"><pre><span></span><span class="n">logger</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;my_library&quot;</span><span class="p">);</span>
+<span class="n">mock</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span><span class="w"> </span><span class="n">failure</span><span class="p">);</span>
+
+<span class="c1">-- Code to trigger the error</span>
+
+<span class="k">wait</span><span class="w"> </span><span class="k">until</span><span class="w"> </span><span class="n">mock_queue_length</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="n">rising_edge</span><span class="p">(</span><span class="n">clk</span><span class="p">);</span>
+<span class="n">check_only_log</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Some error message&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">failure</span><span class="p">);</span>
+<span class="n">unmock</span><span class="p">(</span><span class="n">logger</span><span class="p">);</span>
+</pre></div>

docs/logging/mocking.html

@@ -0,0 +1,9 @@
+<div class="highlight"><pre><span></span><span class="n">logger</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="n">get_logger</span><span class="p">(</span><span class="s">&quot;my_library&quot;</span><span class="p">);</span>
+<span class="n">mock</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span><span class="w"> </span><span class="n">failure</span><span class="p">);</span>
+
+<span class="c1">-- Code to trigger an error</span>
+
+<span class="c1">-- Verify that the expected error message has been produced</span>
+<span class="n">check_only_log</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Some error message&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">failure</span><span class="p">);</span>
+<span class="n">unmock</span><span class="p">(</span><span class="n">logger</span><span class="p">);</span>
+</pre></div>

docs/logging/print.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span><span class="n">print</span><span class="p">(</span><span class="s">&quot;Message to stdout&quot;</span><span class="p">);</span>
+<span class="n">print</span><span class="p">(</span><span class="s">&quot;Append this message to an existing file or create a new file if it doesn&#39;t exist&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;path/to/file&quot;</span><span class="p">);</span>
+<span class="n">print</span><span class="p">(</span><span class="s">&quot;Create new file with this message&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;path/to/file&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">write_mode</span><span class="p">);</span>
+</pre></div>

docs/logging/print_to_open_file.html

@@ -0,0 +1,2 @@
+<div class="highlight"><pre><span></span><span class="n">print</span><span class="p">(</span><span class="s">&quot;Message to file object&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">my_file_object</span><span class="p">);</span>
+</pre></div>

docs/logging/set_debug_option.html

@@ -0,0 +1,3 @@
+<div class="highlight"><pre><span></span><span class="n">testbenches</span> <span class="o">=</span> <span class="n">lib</span><span class="o">.</span><span class="n">get_source_files</span><span class="p">(</span><span class="s2">&quot;*tb*&quot;</span><span class="p">)</span>
+<span class="n">testbenches</span><span class="o">.</span><span class="n">set_compile_option</span><span class="p">(</span><span class="s2">&quot;rivierapro.vcom_flags&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;-dbg&quot;</span><span class="p">])</span>
+</pre></div>

docs/logging/set_format.html

@@ -0,0 +1,3 @@
+<div class="highlight"><pre><span></span><span class="n">set_format</span><span class="p">(</span><span class="n">display_handler</span><span class="p">,</span><span class="w"> </span><span class="n">level</span><span class="p">);</span>
+<span class="n">info</span><span class="p">(</span><span class="s">&quot;Hello world&quot;</span><span class="p">);</span>
+</pre></div>

docs/logging/set_format_log.html

@@ -0,0 +1,2 @@
+<div class="highlight" style="background: #002b36; color: #eee8d5;"><pre style="line-height: 125%; background: #002b36; color: #eee8d5;"><span style="font_weight: bold; color: #eee8d5; ">INFO</span> - Hello world
+</pre></div>

docs/logging/src/path/to/file

@@ -0,0 +1,2 @@
+Create new file with this message
+Message to file object