clash-ffi - Clash FFI with Simulator Tools

Warning

This project is archived, no longer maintained, and should no longer be used. It remains available only to preserve its source and history after being split out of the clash-lang/clash-compiler repository.

• See the LICENSE file for license and copyright details

Clash FFI

This package provides FFI support for interfacing with simulation tools over a standard interface (e.g. VPI / VHPI / FLI). Currently only VPI is supported.

Build the library and tests with:

cabal build all
cabal test all

All interaction with a simulator follows the same general process:

• The Haskell code performing the FFI is compiled as a foreign shared library. To this end, your project's cabal must be extended by a foreign-library section, e.g.,

  foreign-library <my-clash-ffi-lib-name>
    default-language: Haskell2010
    includes:         vpi_user.h
    include-dirs:     </path/to/vpi_user.h>
    build-depends:    clash-ffi,
                      ...
    type:             native-shared
    lib-version-info: 0:1:0
    cpp-options:      -DVERILOG=1 -DIVERILOG=1 -DVERILOG_2001=1 -DVERILOG_2005=1 -DVPI_VECVAL=1
    ...

  See vpi_user.h for more details on the possible cpp-options. You can either use the vpi_user.h, which is shipped with this project, (see the include directory) or the one that's usually provided by the simulator. Note that clash-ffi gets included just like any other standard Haskell library to your project at this point.

• Cabal creates libraries in some hard to access nested sub-directory with a file ending that depends on your operating systems, which is not well suited for the usage in the context of VPI. To get around this, we recommend adding a custom setup to your cabal file:

  custom-setup
    setup-depends: base, Cabal, directory, filepath

  using the Setup.hs of the example project in the example folder (copied to your project's root). This custom setup places the created foreign library into a lib folder created under your project's root and renames the file accordingly. It is important that the library has a .vpl ending to be used by a VPI simulator in the end.

• From this point on, development of your foreign-library works like for a normal Haskell library. For interfacing with the simulator, you just need to have one exposed module within your setup that exports the Clash FFI entry point:

  foreign export ccall "clash_ffi_main"
    ffiMain :: IO ()
  
  ffiMain :: IO ()
  ffiMain = -- Some FFI code

  This main action is run during the start-of-simulation callback of the simulator. This means while it can register new callbacks, it should not run forever as doing so would mean control is never returned to the simulator.

• The simulator is started with flags which load the library. For instance, with iverilog the simulator is invoked with a command similar to

  vvp -L lib -l libclashffi-iverilog-vpi MODULE.vvp

• The example folder contains a minimalistic project utilizing clash-ffi. Check the run-iverilog.sh script in the folder for a quick overview of how to use clash-ffi. The script may be executed within the example folder. It expects the clash executable and simulator tools to be available on PATH. If it does not work for you out-of-the-box, feel free to adapt it according to your local setup.

Supported API Functions

VPI

General Functions

VPI Definition	Supported	Haskell API Function(s)
vpi_chk_error	YES	simulationError, simulationErrorLevel
vpi_compare_objects	YES	compareHandles
vpi_control	YES	controlSimulator
vpi_flush	YES	simFlushIO
vpi_get	YES	getProperty
vpi_get_cb_info	YES	callbackInfo
vpi_get_data	NO
vpi_get_delays	NO
vpi_get_str	YES	getProperty
vpi_get_systf_info	NO
vpi_get_time	YES	simulationTime
vpi_get_userdata	NO
vpi_get_value	YES	receiveValue, unsafeReceiveValue
vpi_get_vlog_info	YES	simulatorInfo
vpi_handle	YES	childHandle
vpi_handle_by_index	YES	childHandle
vpi_handle_by_multi_index	YES	childHandle
vpi_handle_by_name	YES	childHandle
vpi_handle_multi	NO
vpi_iterate	YES	iterate, iterateAll
vpi_mcd_close	NO
vpi_mcd_flush	NO
vpi_mcd_name	NO
vpi_mcd_open	NO
vpi_mcd_printf	NO
vpi_mcd_vprintf	NO
vpi_printf	YES	simPutStr, simPutStrLn
vpi_put_data	NO
vpi_put_delays	NO
vpi_put_userdata	NO
vpi_put_value	YES	sendValue, unsafeSendValue
vpi_register_cb	YES	registerCallback
vpi_register_systf	NO
vpi_remove_cb	YES	removeCallback
vpi_scan	YES	scan
vpi_vprintf	NO

Specific to IEEE 1364

VPI Definition	Supported	Haskell API Function(s)
vpi_free_object	YES	freeHandle

Specific to IEEE 1800

VPI Definition	Supported	Haskell API Function(s)
vpi_get64	YES	getProperty
vpi_release_handle	YES	freeHandle

VHPI

VHPI is not supported at this time.

FLI

FLI is not supported at this time.