QUICK_START

OCSE Quick Start Guide

SETUP:

1) Use "make" to compile the code in the directory ocse. You will have to first
        set the appropriate #define in common/tlx_interface_t.h to select the TLX
        version you want to work with; be sure to do a "make clean" before your make. 
	This creates a stand-alone executable that mimics the behavior of 
	OpenCAPI/TLx and the linux reference kernel code that supports it.

2) Use "make" to compile the code in the directory libocxl.  This creates both
	libocxl.a archive library version of libocxl as well as libocxl.so shared
	object version of libocxl.  Routines in libocxl are used by your "host application"
	to intialize communications with your fpga hardware design

3) Use "make" to build the code in afu_driver/src.  You will have to first set
	the environment variable VPI_USER_H_DIR.  The value must point to the
	directory that contains the file "svdpi.h".  This file is provided
	by the Verilog simulator.  "make" will build "veriuser.sl" and
	"libdpi.so" for your simulator.  Refer to your simulator's
	documentation for details on how to use the SystemVerilog DPI.  You will only
	need 1 of these files.  Which one will depend on your simulator.
	- we need to point to the "svdpi.h" file which will be present at the simulation tool's 
	  "include" directory
	- the Makefile ensures that the appropriate env variable "VPI_USER_H_DIR" is set
	- the Makefile will set "VPI_USER_H_DIR" depending on certain simulate specific 
	  "install" environment variables 

4) Use top.v in afu_driver/verilog as a top level wrapper around your AFU
	Verilog.  Build a model as required for your simulator.  You may need to set flags
	or options to allow SystemVerilog keywords as top.v include references to
	C code that uses SystemVerilog DPI functionality.

5) Look at the Makefiles in sample_app for examples of how to build your
	application with libocxl.  If you build with libocxl.so then you don't
	have to re-compile your application if libcxl changes.  You can just
	re-compile libocxl and libocxl.so is picked up at runtime.  However, this
	method requires the the environment variable LD_LIBRARY_PATH contains
	the libocxl path at runtime.  Alternatively, you can compile with
	libcxl.a.  When using libcxl.a you don't need to set any environment
	variables but you do need to recompile your application any time that
	libocxl is recompiled.

6) Use sample_app/app.c as an example to start coding your application with
	libocxl calls using the functions in libocxl.h.

7) Build your application.


RUNNING:

1) Start your simulator with the model that uses top.v as it's top level and
   uses the afu_driver/src code for DPI functions.  Most simulators use LD_LIBRARY_PATH
   to find the afu_driver/src compiled code and DPI libraries.  Check with your simulator
   for complete details.  Allow your simulator to advance time and you should eventually 
   get a message in the simulator output similiar to this: 
   "AFU Server is waiting for connection on machine.domain.com:32768"

2) Edit ocse/shim_host.dat to point an AFU at your simulator.  For example:
     afu0.0,machine.domain.com:32768
   If necessary, set the SHIM_HOST_DAT environment variable to override the
   path to this file.

3) Edit ocse/ocse.parms as desired, or leave the defaults to get started.
   If necessary, override the path to this file using the OCSE_PARMS
   environment variable.

4) Optional: If you need to specify a non-default path for configuration or log
   files, use these environment variables:
     SHIM_HOST_DAT: specifies path to the `shim_host.dat` file.
     OCSE_PARMS: specifies path to the `ocse.parms` file.

5) Start ocse with ./ocse in pslse directory.  If time is advancing in the simulator,
   ocse will connect to the simulator, perform a set of afu configuration and discovery
   steps and you will eventually see a message from ocse with a 
   hostname and port similiar to this:
     "INFO : Started OCSE server, listening on machine.domain.com:16384"
   indicating it is ready for a host application to run and connect to ocse.

6) In the directory where you will run your application code create the file
   ocse_server.dat and put the host:port provided by pslse in it.  For
   example:
     machine.domain.com:16384

7) Start your application.  Run your application multiple times if desired.
   If necessary, override the path to the `ocse_server.dat` file using the
   OCSE_SERVER_DAT environment variable.

8) When run is complete you can stop the ocse executable with Ctrl-C to cleanly
   disconnect from the simulator.  You may need to advance simulation time
   a little to allow ocse to complete the shutdown sequence.

Note: We'll accept vendor specific simulator start up text files.