ghdlex opensource distribution
----------------------------------------------------------------------------

This demonstrates usage of threading to remote control a VHDL simulation
from a C program (or Python via netpp, optionally).
This library can be used to deploy networked swarms of independent
simulation test bench executables generated by GHDL
(https://github.com/ghdl/ghdl)

----------------------------------------------------------------------------
QUICK DEPLOYMENT
----------------

For the impatient, there is a docker container with all necessary tools
preinstalled.

> docker run -it -p 7208:7208/udp -p 2010:2010/tcp \
  hackfin/masocist 

.. go for a coffee ..

Inside the container:

$ git clone https://github.com/hackfin/ghdlex.git
$ cd ghdlex; make all

Once the simulation examples were built (try `ls sim*` to verify), 
you can run them after you've set the LD_LIBRARY_PATH:

$ export LD_LIBRARY_PATH=`pwd`/src

$ ./simboard


-----

Listening on UDP Port 2010...
Listening on TCP Port 2010...
Reserved RAM ':simboard:ram0:' with word size 0x1000(8192 bytes), width: 16 bits
Registered RAM property with name ':simboard:ram0:'
Reserved RAM ':simboard:ram1:' with word size 0x1000(8192 bytes), width: 16 bits
...

-----

Inside the container, you can use the 'netpp' command to access the simulation.
From the outside, the '-p' flags from above come into play for port forwarding.

If running on a Windows host OS, you will have to install the netpp client
according to

https://section5.ch/index.php/2017/09/12/netpp-for-windows-quick-start/


----------------------------------------------------------------------------

List of example simulations:


* simpty: Virtual PTY. See examples/pty.vhdl on how to initialize a
          a PTY using socat. This example can be used to build a true
          virtual UART.

These are netpp featured and will not be compiled by default (unless you
have netpp installed and pass the installation directory to 'make' using
the NETPP variable or an extra custom 'config.mk'.

* simnetpp: A client example. Connects to the netpp example device (see
  devices/example/slave) and modifies the "ControlReg" property remotely.

* simfb: Connects to the remote 'display' server and shows a 256x256
  YUV color test image.

* simboard: Simulates a virtual board with various virtual I/O's,
            virtual RAM, FIFOs, etc.

To compile the example, run 'make'. You will end up with a simulation
executable 'simboard' plus a src/libghdlex.so or src/libghdlex-netpp.so DLL.

To run the simulation, you have to add the path to this DLL to the
LD_LIBRARY_PATH, for instance:

> export LD_LIBRARY_PATH=`pwd`/src:$LD_LIBRARY_PATH

Then you can run the simulation:

> ./simboard --stop-time=500ms --wave=test.ghw

Use gtkwave to look at the traces:

> gtkwave test.ghw

To build the netpp featured variants, run

> make allnetpp

and wait for things to finish. You may have to run a "make clean" before that.

Cross compiling GHDLEX is only supported for mingw32. Run
	
> make MINGW32=1

to compile a library for the i686-w64-mingw32 cross compiler.

----------------------------------------------------------------------------
NETPP FEATURES

To test if your simulation is accessible through netpp, try this:

1) Start an example simulation, like simboard:

> ./simboard

2) Run the netpp client 'master':

> ./netpp/master/master TCP:localhost:2010

This will output the properties of your virtual board:

Properties of Device 'VirtualBoard' associated with Hub 'TCP':
Child: [80000001] ':simboard:ram0:'
Child: [80000002] ':simboard:ram1:'
...


Likewise, you could mess with the simple FIFO loopback test implemented
in examples/board.vhdl:

> python py/board.py

This shows how the simulation is (remotely) accessed by a python script.

----------------------------------------------------------------------------
LIBRARY OPTIONS

As you might have figured out, there are two ways to enhance your VHDL
simulation:
1) By just adding the --vpi=netpp.vpi flag: This quickly exports the top level
   signals to netpp without you requiring to explicitely register anything.

2) By explicitely initializing NETPP from your simulation. See doxygen
   documentation.



----------------------------------------------------------------------------
EXPERIMENTAL

GHDL provides another way of extension via the VPI interface. This allows
to export pin names and manipulate signals by external DLLs that are loaded
dynamically. The netpp.vpi module gathers all signals from the top module
interface or virtual hardware modules and exports them to a netpp server,
meaning, they can be accessed and manipulated from outside via a netpp
client. This is based on a netpp version >=0.40 with support for dynamic
properties.
Since this approach makes use of multiple threads, it may not be 100% safe
for signal manipulation. This way of signal manipulation is also limited,
and not timing-accurate.

----------------------------------------------------------------------------

More details about netpp:
  http://www.section5.ch/netpp

For all other details: Read the source, Luke.

For usage information, see LICENSE.txt


Have fun!

----------------------------------------------------------------------------
2011-2014, <hackfin@section5.ch>