WIP vhpidirect: add 'quickstart/cli'

doc/vhpidirect/examples/quickstart.rst

@@ -157,3 +157,37 @@ data through an access/pointer. This approach is more verbose than others, but i
 2008 without modification and without requiring :option:`-frelaxed`. Moreover, it enhances encapsulation, as it provides
 a user-defined API between VHDL and C, which can improve maintainability when sources are reused. As a matter of fact,
 this approach is found in verification projects such as `VUnit <http://vunit.github.io/>`_ and `OSVVM <https://osvvm.org/>`_.
+
+:cosimtree:`Command-Line Arguments <vhpidirect/quickstart/cli>`
+***************************************************************
+
+Top-level generics
+==================
+
+As explained in :ref:`simulation_options`, there is no standard methos in VHDL to obtain arguments. However, GHDL allows to override top-level generics, with certain restrictions. See :option:`-gGENERIC` for further details.
+
+In this example, two top-level generics of types ``string`` and ``integer`` are set at runtime through CLI arguments.
+
+Parsing/customizing ``argv``
+============================
+
+By the same token, ``ghdl_main`` receives ``argc``, ``argv`` and ``env`` as any regular ``main`` function in C. Hence, when GHDL is wrapped as explained in :ref:`Starting_a_simulation_from_a_foreign_program`, it is possible to either pass raw arguments or to process them before calling ``ghdl_main``. Hence, overrides for top-level generics can be defined in C sources. Alternatively, the default value defined in VHDL can be set to a function call.
+
+This example showcases multiple approaches to manipulate top-level generics when GHDL is wrapped.
+
+- rawargs: pass argc and argv without modification. ``-gSIZE=5``
+- procargs: pass argc and argv by adding options. ``-s 5``, ``-s=5`` (atoi)
+- fcnargs: pass argc and argv without modification, but use a function call to set the default of top-level generics.
+- separgs: some more elaborate argv parsing to split based on ``[c options] -- [ghdl options]``. What to do when ``--`` is not found? Are all args for C or for ``ghdl_main``? ``--verbose -- -gSIZE 5``
+
+Setting parameters in C through VHDL generics
+=============================================
+
+VHDL can pass a generic to C when calling a subprogram. Although this might feel as a rare use case, it is easy for it to happen when adapting a design that is not aware of VHPIDIRECT features, and we want to optionally enhance it with them.
+
+JSON-for-VHDL
+=============
+
+`JSON-for-VHDL <https://github.com/Paebbels/JSON-for-VHDL>`_ is a synthesizable VHDL library that allows to provide configuration parameters through either a JSON file or an stringified (and optionally base16 encoded) top-level generic. Together with `jq <https://stedolan.github.io/jq/`_ or the libraries available for almost any language, it is a very powerful resource to pass large amounts of params with minimal maintenance effort.
+
+Examples are available at `Paebbels/JSON-for-VHDL:tests <https://github.com/Paebbels/JSON-for-VHDL/tree/master/tests>`_.

vhpidirect/quickstart/cli/fcnargs.c

@@ -0,0 +1,5 @@
+#include <stdio.h>
+
+int main(int argc, char** argv) {
+  printf("fcnargs\n");
+}

vhpidirect/quickstart/cli/procargs.c

@@ -0,0 +1,5 @@
+#include <stdio.h>
+
+int main(int argc, char** argv) {
+  printf("procargs\n");
+}

vhpidirect/quickstart/cli/rawargs.c

@@ -0,0 +1,5 @@
+#include <stdio.h>
+
+int main(int argc, char** argv) {
+  printf("rawargs\n");
+}

vhpidirect/quickstart/cli/run.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd $(dirname "$0")
+
+echo "> Analyze tb.vhd"
+ghdl -a tb.vhd
+
+
+echo "> Build tb (with rawargs.c)"
+ghdl -e -Wl,rawargs.c -o tb_rawargs tb
+
+echo "> Execute tb_rawargs"
+./tb_rawargs
+
+
+echo "> Build tb (with procargs.c)"
+ghdl -e -Wl,procargs.c -o tb_procargs tb
+
+echo "> Execute tb_procargs"
+./tb_procargs
+
+
+echo "> Build tb (with fcnargs.c)"
+ghdl -e -Wl,fcnargs.c -o tb_fcnargs tb
+
+echo "> Execute tb_fcnargs"
+./tb_fcnargs
+
+
+echo "> Build tb (with separgs.c)"
+ghdl -e -Wl,separgs.c -o tb_separgs tb
+
+echo "> Execute tb_separgs"
+./tb_separgs

vhpidirect/quickstart/cli/separgs.c

@@ -0,0 +1,5 @@
+#include <stdio.h>
+
+int main(int argc, char** argv) {
+  printf("separgs\n");
+}

vhpidirect/quickstart/cli/tb.vhd

@@ -0,0 +1,10 @@
+entity tb is
+end entity;
+
+architecture arch of tb is
+begin
+  process begin
+    report "Hello linking/bind!" severity note;
+    wait;
+  end process;
+end;