WIP vhpidirect: add 'quickstart/cli'

doc/vhpidirect/examples/quickstart.rst

@@ -91,3 +91,34 @@ 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:`cli <vhpidirect/quickstart/cli>`
+********************************************
+
+Top-level generics
+==================
+
+Parsing/customizing ``argv``
+============================
+
+It is feasible to have some size defined by a generic in VHDL, but have it defined in C in practice, by passing it as a ``-gGENERIC=`` to ghdl_main.
+
+I think it would be better to use/parse argv[1]. Three options:
+
+* If ``argc == 1``, use ``argv[1]`` as an integer (atoi).
+* Pase argv and look for ``--size=`` or ``-s``. Then use atoi as in the previous point.
+* Search for ``--`` in argv and consider all previous args to be "custom args for C". Then search for ``--size`` or ``-s`` as in the previous point. Pass args after ``--`` to GHDL. Open question would be: what to do when ``--`` is not found? Are all args for C or for ``ghdl_main``?
+
+Either of these would be interesting because they'd show how to add custom args (that need to be removed from the argv passed to GHDL). I would not use any lib such as optargs, tho. We want to support a single custom argument.
+
+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>`_.