Installation and Easy Get Started

Kiwi is currently not as easy to use as it could be. You can find an `addin' for the monodevelop IDE on the following URL but it is currently not very useful and since it is really focussed on Kiwi performance prediction which is immature. Currently it is best if you craft a makefile based on one of the examples.

Monodevelop addin: http://www.cl.cam.ac.uk/users/djg11/kiwi/kiwiaddins/KiwiScientificAssist.

The makefile will compile your application and optionally run the application on your workstation under mono or the Windows equivalent.

The makefile will then invoke the Kiwi compiler to generate a Verilog RTL file and combine this with the provided substrate Verilog files for your FPGA target. Finally it will invoke the FPGA tool suite to give a bitstream file to be loaded to the FPGA.

The means for loading to the FPGA is currently highly-platform specific. Each substrate should have its own user guide.

Get Started (Mono on Linux)

Kiwi can be supplied in source or binary form.

Requirements:. You need a working dotnet environment (mono or Windows) on your machine including a C# compiler. It is also handy to have icarus Verilog and Verilator and SystemC.

Do not do this for Windows, but for linux set your shell environment MONO variable

$ setenv MONO=mono
$

KiwiC/HPR is currently internally implemented in F# but you just need a C# compiler to use it.

Kiwi binary form is normally supplied as a zip file that contains folders called lib, bin, doc and so on. If you want the source for the compiler please ask.

An open source release is planned January 2017. You will need the F# compiler to compile HPR and KiwiC from source. The source build should be configured by editing the paths in hpr/Makefile.inc. Set the HPRLS shell variable to where the source code sits and run `make' in kiwipro/kiwic/src to build the compiler.

If F# is not locally installed you will need to manually add at least the FSharpCore.dll to the KiwiC/distro/lib folder. We do ship one you can move there. Otherwise you may get 'type load' and 'missing entry point' errors.

FSharp can be simply obtained with apt-get install fsharp on some machines.

KiwiC uses the Mono.Cecil front end and hence the Mono.Cecil.dll is required, either installed on the machine or copied to the KiwiC/distro/lib folder.

Place the KiwiC distribution somewhere on your filesystem. Let us call that place PREFIX. For source build this will be $HPRLS/kiwipro/kiwic/distro/lib. To run KiwiC on linux you must execute the KiwiC shell script

  $ $(PREFIX)/bin/kiwic ... args ...
The shellscript just contains mono $(PREFIX)/lib/kiwic.exe

Windows users can invoke the kiwic.exe executable directly.

The arguments to KiwiC should either be portable assembly files (suffix .dll or .exe) or option flags prefixed with a minus sign. Generally you will supply the current design and KiwiC will automatically load the Kiwi libraries it needs.

Two Kiwi libraries are commonly needed:

  1. Kiwi.dll - This defines the Kiwi attributes and other material implemented in C# that should be supplied both to C# compilations and to the KiwiC compiler for both FP and WD.

  2. Kiwic.dll - This defines additional or replacement implementations of standard .NET library functions for use by the KiwiC compiler and must nominally be supplied on the KiwiC command line. Generally, this is not needed for the first stage of a compilation when an application program in C# is converted to a .NET binary (.exe or .dll) where that binary is either going to be run on the workstation (mono/windows) or compiled further by KiwiC. It should be automatically found by KiwiC and so does not need to be actually named on any command line.

    To enable the same RTL file to be synthesised for FPGA by vendor tools and simulated [RTLSIM] but to have slightly different behaviour (e.g. w.r.t. BIST self test) it is handy to define an external input to the Kiwi code that you tie low in the RTLSIM testbench but strap high in the FPGA substrate pad ring.

      [Kiwi.InputBitPort("FPGA")] static bool FPGA;
    

If you have these libraries in .cs form only, you will need to compile them to .dll form using mcs or similar. You will get some warnings about the `unsafe' code they contain.

You must manually include the reference to Kiwi.dll in the C# compilation step.

For the KiwiC compilation step, KiwiC will automatically search for the above libraries and include them in the compilation and this is equivalent to manually including them on the KiwiC command line.

To disable automatic search or redirect it to specific files, use the command-line flags -kiwic-dll and -kiwi-dll. Set these to the empty string to disable them or set them to a specific location, e.g. -kiwic-dll=/usr/lib/kiwic/mykiwic.dll.

Note that anything specified via the command line can also be specified in an XML recipe file, with the command line taking precedence when specified both ways. Kiwi comes with a standard recipe for accelerating scientific computing. You can modify this to get SystemC output or for privately developed flows based on Kiwi.

Kiwi defines the terms WD, RTLSIM and FP to define three execution environments.

  1. WD -- Rapid development of applications on the workstation with performance prediction.
  2. RTLSIM -- Verilog simulation (verilator is fastest) in case of KiwiC bugs and for performance calibration when interacting with RTL models of other system components.
  3. FPGA -- high-performance execution on the FPGA.

The Kiwi.HardwareEntryPoint attribute can be attached to one or more static methods in the input program. The control-flow graph beneath such methods is converted to hardware. The command line -root flag is another way of specifiying an entry point. KiwiC does not default to using a static Main method.

The HardwareEntryPoint attribute can take a pause mode as an argument. This will, in future, set the starting pause mode for that entrypoint, and moreover, be used to set pipelined accelerator mode.

To obtain Verilog RTL output, KiwiC requires a source file name and access to its libraries. So the most basic Makefile is something like

It might be helpful to pass constant values as arguments to the HardwareEntryPoint but this is not supported. Instead, write a C# shim that takes no arguments and passes constants to a putative entry point.

PREFIX=$(HPRLS)/kiwipro/kiwic/distro
KLIBC=$(PREFIX)/kiwipro/support/Kiwic.dll
KLIB0=$(PREFIX)/kiwipro/support/Kiwi.dll
KIWIC=$(PREFIX)/kiwipro/bin/kiwic 

all:
	gmcs /target:library tiny.cs /r:$(KLIB0) 
	$(KIWIC) tiny.exe


# Other useful options until recently:  -vnl and -root:
        $(KIWIC) tiny.exe  -root "tiny;tiny.Main" -vnl tiny.v

Given that you have a file called tiny.exe to hand, this should result in a file called tiny.v in your current directory.

To generate tiny.exe one can do the following:
\begin{quoze}
$ cat > tiny.cs
using System;
using KiwiSystem;
\par
class tiny
{
...
...;
return 1;
}
}
$ gmcs tiny.cs  ...

Should you need it, KiwiC will write a disassembly of the PE file to obj/ast.cil in the current folder, enabled by recipe or command line flag `-kiwic-cil-dump=separately' or `-kiwic-cil-dumpl=combined'.

If you do not have the Kiwi.dll library to hand (e.g. input from C++ instead of C#) or have other problems putting a HardwareEntryPoint attribute on a method then using the -root command line flag is a good idea.

If you do not have the Kiwi.dll library to hand (e.g. input from C++ instead of C#) or have other problems putting a HardwareEntryPoint attribute on a method then using the -root command line flag is an alternative.

Also, you can externally disassemble a .net CIL file using ikdasm (which works better than the older monodis) shell command. The command pedump may also be useful.



Subsections
David Greaves 2016-12-04