README

xBGAS-RUNTIME
contact@tactcomplabs.com
--------------------------------------------------------------------------------

I.  Overview
--------------------------------------------------------------------------------

The xBGAS Runtime Library is designed for SST simulation and enables OpenSHMEM-like functionality for xBGAS-enabled RISC-V architectures. Written in a combination of C and Assembly, it provides high-performance SHMEM operations, including “Get”, “Put” and "Collectives" functionality, for other libraries and users.


II. Requirements
--------------------------------------------------------------------------------

To run and simulate xBGAS applications, the following components are required::
- SST: http://sst-simulator.org/
- REV-xBGAS: https://github.com/artlands/rev-xbgas

To build the xBGAS runtime library, you will need:
- xBGAS RISC-V GNU Compiler Toolchain: https://github.com/artlands/riscv-gnu-toolchain-xbgas
- CMake 2.6+

Environment Variables: Ensure the following are set before building:
- $REV: Path to the REV-xBGAS development directory (for system call linking).
- $RISCV: Path to the xBGAS GNU compiler toolchain.
- $XBGAS_RUNTIME: Target installation directory for the xBGAS runtime library.

III.  Compiling
--------------------------------------------------------------------------------

To compile the xBGAS runtime library, follow these steps:

$> git clone https://github.com/artlands/rev-xbgas-runtime.git
$> cd xbgas-runtime
$> mkdir build
$> cd build
$> cmake ../
$> make -j

Optional CMake Build Arguments:
- -DCMAKE_BUILD_TYPE=Debug : Build with debug symbols.
- -DCMAKE_BUILD_TYPE=Release : Optimized release build (default).
- -DBUILD_DOCUMENTATION=ON : Generate documentation (requires Doxygen). Build with "make doc"

IV.   Installation
--------------------------------------------------------------------------------

Once compiled, install the library, headers, and documentation using:
$> make install

V.    Testing
--------------------------------------------------------------------------------

The xBGAS runtime library includes a built-in test harness within the CMake infrastructure.

To build and run tests, include the following CMake argument:
- -DBUILD_ALL_TESTING=ON : Enable all tests.

Alternatively, enable specific test blocks using the following options:
- -DBUILD_INIT_TESTING=ON   : xBGAS runtime initialization/close tests
- -DBUILD_ALLOC_TESTING=ON  : Allocation and free tests
- -DBUILD_PUT_TESTING=ON   : Put tests
- -DBUILD_GET_TESTING=ON   : Get tests
- -DBUILD_AMO_TESTING=ON   : Atomic memory operation tests

Once built, run the tests with:

$> make test
--------------------------------------------------------------------------------
EOF