first commit

content/chapter4/page8.md

@@ -0,0 +1,46 @@
++++
+title = "Calling foreign functions"
+weight = 1
++++
+
+A function can be declared to be foreign which means that its
+implementation is not in BH.
+
+
+```
+topDefn ::= foreign varId :: type [= string ] [ , ( {string }) ]
+```
+
+The optional string gives the name of the external "function" to use. If
+no string is given the same name as the BH name is used. The optional
+strings in parentheses are the port names of the Verilog module that
+implements the function. Without port names positional arguments will be
+used.
+
+Example:
+
+```hs
+foreign countOnes :: Bit n -> Bit 32 = "pop_count"
+```
+
+
+A call to `countOnes` will instantiate the Verilog `pop`` ``count`
+module. It should have the same number of arguments (with the same type)
+as the BH function, *and* an additional trailing argument which is the
+result. If the function is (size) polymorphic the instantiated types
+will be used as Verilog parameters.
+
+
+Example: using the declaration above an action, with the type of `x`
+being `Bit 5`,
+
+```hs
+y := countOnes x
+```
+
+
+will translate to something like
+
+```hs
+pop_count #(5) ires1(R_x, I_y);
+```