=======================
Importing Foreign C Lab
=======================

This lab is composed of simple exercises to develop familiarity with
the "Direct C" feature in BSV.  The first exercise explores the tool
flow with a pre-written design and the second exercise explores the
import-BDPI syntax by finishing an incomplete design.

* Part 1: Tool Flow

This exercise is to develop familiarity with the compilation flow for
designs with imported foreign functions.  The file "DirectC_Part1.bsv" is
a pre-written design which imports three functions (two value
functions and one Action function) and uses them in a one-cycle
simulation.  The C functions are contained in the file "funcs1.c.keep",
which you should copy to the file "funcs1.c":

   # cp funcs1.c.keep funcs1.c

(It exists with the "keep" extension to prevent the file from being
deleted when you "make clean".)

The commands for compiling and simulating with foreign functions are
documented in the BSC User Guide, Section 7, "Importing functions from C
(the Bluespec Direct Programming Interface)".

Using what you have learned from the documentation and the slide
presentation, compile and simulate the module "mkDirectC_Part1" contained
in the file "DirectC_Part1.bsv".  When you have successfully simulated the
design, you should see the numbers 0 and 3 output to the screen.

You can compare the commands that you used with the commands given in
the solution file "DirectC_Part1_Solution.txt".

* Part 2: import-BDPI Syntax

This exercise is to develop familiarity with writing import-BDPI
statements to import C functions into a BSV design.  The file
"DirectC_Part2.bsv" is a nearly-complete design which uses 4 imported
functions: rand32, my_print, dup4, and poly_invert.

These functions should be imported with import-BDPI statements in
the file "Part2Imports.bsv".  This file is currrently empty.  It is
your assignment to fill in the contents of the file.

The design has a top module "mkDirectC_Part2" which sends a random number
to the submodule then waits for a response.  When it receives a
response, it compares the response to an expected value and displays
"Success" or "Fail".  This continues for 10 random numbers and then
the simulation stops.  The random number comes from a C function and
the display is performed by a C function.

The submodule receives requests and returns the value concatenated
with itself 4 times and then inverted (that is, "{v,v,v,v}").  These
operations are implemented by C functions.

The C functions are contained in the file "funcs2.c.keep", which you
should copy to the file "funcs2.c":

   # cp funcs2.c.keep funcs2.c

The expected output of the module is contained in the file
"mkDirectC_Part2.out.expected".

Fill in the contents of "Part2Imports.bsv" and check that the
simulation gives the expected output.  You can then check your
imports against the solution given in the file "Part2Imports_Solution.bsv"


----------
End of Lab