Merge pull request #2429 from clash-lang/ffi-fixes

Make `clash-ffi` a haskell library + FFI interface tests

.ci/gitlab/test.yml

@@ -133,6 +133,17 @@ suite:cores:
     - local
     - vivado-2022.1-standard
 
+ffi:interface-tests:
+  extends: .test-cache-local
+  script:
+    - ./dist-newstyle/build/*/*/clash-ffi-*/x/ffi-interface-tests/build/ffi-interface-tests/ffi-interface-tests --smallcheck-max-count 2000
+
+ffi:example:
+  extends: .test-cache-local
+  script:
+    - cabal build clash # ensure clash has been built (avoids some legacy cabal issue)
+    - cd clash-ffi/example && ./run-iverilog.sh
+
 
 # Tests run on local fast machines with Vivado installed. We only run these at night
 # to save resources - as Vivado is quite slow to execute.

clash-ffi/README.md

@@ -9,16 +9,52 @@ a standard interface (e.g. VPI / VHPI / FLI). Currently only VPI is supported.
 
 All interaction with a simulator follows the same general process:
 
-  * the Haskell code performing the FFI is compiled as a shared library. Any
-    libraries specified as `foreign-library` in `clash-ffi.cabal` are copied
-    into a `lib/` directory in the project on successful build. Haskell FFI
-    code *must* export the entry point
+  * 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.,
+
+    ```cabal
+    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
+      ...
+    ```
 
-    ```c
-    void clash_ffi_main(void);
+    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:
+
+    ```cabal
+    custom-setup
+      setup-depends: base, Cabal, directory, filepath
     ```
 
-    This requires a foreign export in user code, i.e.
+    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:
 
     ```haskell
     foreign export ccall "clash_ffi_main"
@@ -28,9 +64,10 @@ All interaction with a simulator follows the same general process:
     ffiMain = -- Some FFI code
     ```
 
-    This main action is run during the start-of-simulation callback from VPI.
-    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.
+    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
@@ -39,6 +76,13 @@ All interaction with a simulator follows the same general process:
     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 `examples` folder. If it does not work for you
+    out-of-the-box, feel free to adapted it according to your local
+    setup.
+
 ## Supported API Functions
 
 ### VPI

clash-ffi/clash-ffi.cabal

@@ -11,50 +11,45 @@ author:             QBayLogic B.V.
 maintainer:         [email protected]
 copyright:          Copyright © 2022, QBayLogic B.V.
 category:           Hardware
-build-type:         Custom
 
-common basic-config
+common common-options
   default-language: Haskell2010
-
   default-extensions:
-    BangPatterns
-    DeriveAnyClass
-    DeriveGeneric
-    DerivingStrategies
-    GeneralizedNewtypeDeriving
     ScopedTypeVariables
     TypeApplications
-
-  include-dirs:
-    include
-
   ghc-options:
     -Wall -Wcompat
-
   build-depends:
     base                    >= 4.11 && < 4.17,
     bytestring              >= 0.10 && < 0.12,
     clash-prelude           >= 1.2  && < 1.8,
     deepseq                 >= 1.4  && < 1.5,
+  include-dirs: include
+  includes: vpi_user.h
+  cpp-options:
+    -DVERILOG=1
+    -DIVERILOG=1
+    -DVERILOG_2001=1
+    -DVERILOG_2005=1
+    -DVPI_VECVAL=1
+
+library
+  import: common-options
+  default-extensions:
+    BangPatterns
+    DeriveAnyClass
+    DeriveGeneric
+    DerivingStrategies
+    GeneralizedNewtypeDeriving
+  build-depends:
     derive-storable         >= 0.3  && < 0.4,
     derive-storable-plugin  >= 0.2  && < 0.3,
     mtl                     >= 2.2  && < 2.3,
-
-  other-modules:
+  hs-source-dirs: src
+  c-sources: cbits/entry_vpi.c
+  exposed-modules:
     Clash.FFI.Monad
     Clash.FFI.View
-
-common vpi-config
-  includes:
-    vpi_user.h
-
-  c-sources:
-    cbits/entry_vpi.c
-
-  cpp-options:
-    -DVERILOG=1
-
-  other-modules:
     Clash.FFI.VPI.Callback
     Clash.FFI.VPI.Callback.Reason
     Clash.FFI.VPI.Control
@@ -81,26 +76,33 @@ common vpi-config
     Clash.FFI.VPI.Port.Direction
     Clash.FFI.VPI.Reg
 
-custom-setup
-  setup-depends:
-    base        >= 4.11  && < 5,
-    Cabal       >= 2.4   && < 3.7,
-    directory   >= 1.3.6 && < 1.4,
-    filepath    >= 1.4.2 && < 1.5,
-
--- To accomodate differences between different simulators when defining the
--- generic interface, different foreign libraries are produced for each tool.
--- The code is shared between all simulators and each library defines it's name
--- and includes the source files it needs for it's interface.
-
-foreign-library clash-iverilog-vpi
-  import: basic-config, vpi-config
-  type: native-shared
-  lib-version-info: 0:1:0
-  hs-source-dirs: src
-
-  cpp-options:
-    -DIVERILOG=1
-    -DVERILOG_2001=1
-    -DVERILOG_2005=1
-    -DVPI_VECVAL=1
+executable ffi-interface-tests
+  import: common-options
+  default-extensions:
+    DataKinds
+    RankNTypes
+    LambdaCase
+    ViewPatterns
+    TupleSections
+    ImplicitParams
+    FlexibleContexts
+    FlexibleInstances
+    MultiParamTypeClasses
+    ExistentialQuantification
+  hs-source-dirs: tests
+  main-is: Main.hs
+  other-modules:
+    Clash.FFI.Test
+    Clash.FFI.Test.Instances
+  include-dirs: tests/cbits
+  c-sources:
+    tests/cbits/VPI.c
+    tests/cbits/Test.c
+    tests/cbits/Pipe.c
+    tests/cbits/Print.c
+  build-depends:
+    , clash-ffi
+    , smallcheck
+    , tasty
+    , tasty-hunit
+    , tasty-smallcheck

clash-ffi/example/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2022 QBayLogic B.V.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.