+---------------------------------------+
| Power Service Layer Simulation Engine |
+---------------------------------------+

This repository contains code for both simulation and real hardware connection
and testing of a customer designed Accelerated Functional Unit (AFU) to the
Power Service Layer (PSL) as part of IBM's CAPI interconnect on Power8 systems.
The repository is broken into 2 directories.  The "libcxl" directory contains
abstraction layer code that interfaces with kernel level "cxl" code for
communicating with an AFU in real hardware.  This code serves two purposes.
First, it provides a simple interface to write code to for interfacing with AFU
devices.  Second, if code is written using this abstraction layer then the same
code can be compiled with an alternate version of libcxl.c and libcxl.h that
exists in the "pslse" directory for co-simulation with the AFU on most
industry standard Verilog simulators.  The "pslse" directory contains the code
to interface with a Verilog simulator.

There is a dependence on a file in the kernel headers for newer 3.18 kernels.
The file is /usr/include/misc/cxl.h.  Without this file on your system you
will not be able to compile libcxl code.  This file can not be included here
as it falls under a different license.

It should be noted that only a handful of functions are currently supported in
both environments.  This list should grow but in programming of applications
should focus only on using the currently supported functions.

Functions currenty supported in both "libcxl" and "pslse":
- struct cxl_afu_h * cxl_afu_open_dev (char *path);
- int cxl_afu_attach (struct cxl_afu_h *afu, __u64 wed);
- void cxl_afu_free (struct cxl_afu_h *afu);
- bool cxl_pending_event (struct cxl_afu *afu);
- int cxl_read_event (struct cxl_afu_h *afu, struct cxl_event *event);
- int cxl_mmio_map (struct cxl_afu_h *afu, __u32 flags);
- int cxl_mmio_unmap (struct cxl_afu_h *afu);
- void cxl_mmio_write64 (struct cxl_afu_h *afu, uint64_t offset, uint64_t data);
- uint64_t cxl_mmio_read64 (struct cxl_afu_h *afu, uint64_t offset);
- void cxl_mmio_write32 (struct cxl_afu_h *afu, uint64_t offset, uint632t data);
- uint32_t cxl_mmio_read32 (struct cxl_afu_h *afu, uint64_t offset);

The "pslse" directory contains the replacement libcxl.c file in addition to a
shim_host.dat file and the two directories afu_driver and psl_interface.
When compiling for simulation the libcxl.c would replace the real hardware
version of libcxl.c during code compilation.  During compile the file in
psl_interface will be needed as well in support of this version of libcxl.c.
The directory psl_interface contains the code for abstracting the PSL-AFU
interface into a network socket connection so that two different programs,
the application and the Verilog simulator, can communicate with each other in
terms of PSL interface transactions.  The afu_driver code contains the code
that will be needed by the Verilog simulator.  The afu_driver code is also
dependent on the code in psl_interface.

The afu_driver directory contains two directories src and verilog.  The verilog
directory contains the file top.v which is a top level wrapper that will
instantiate your AFU Verilog code.  The src directory contains afu_driver.c
which works hand in hand with top.v.  You'll need to modify the Makefile in
src to set SIM_INCLUDE_DIR to point to the directory that contains the file
vpi_user.h necessary for the Verilog PLI 2.0 interface.  This file should be
part of the simulator installation and is completely seperate from this code.
Once this modification has been made then you should be able to "make" the
afu_driver.sl using gcc.  This is the shared code that the Verilog simulator
use for the Verilog PSI 2.0 interface with top.v.  The exact setup details
depend on which simulator you are using.