# OPAE Python Bindings

OPAE (Open Programmable Acceleration Engine) now includes Python bindings for
interacting with FPGA resources. The OPAE Python API is built on top of the
OPAE C++ Core API and its object model. Because of this, developing OPAE
applications in Python is very similar to developing OPAE applications in C++
which significantly reduces the learning curve required to adapt to the Python API.
While the object model remains the same, some static factory functions in the
OPAE C++ Core API have been moved to module level methods in the OPAE Python API
with the exception of the properties class. The goal of the OPAE Python API is
to enable fast prototyping, test automation, infrastructure managment, and an
easy to use framework for FPGA resource interactions that don't rely on software
algorithms with a high runtime complexity.

Currently, the only Python package that is part of OPAE is `opae.fpga`

## Implementation

The OPAE Python API is implemented by creating a Python extension using `pybind11
<http://pybind11.readthedocs.io/en/stable>`_.
This extension is created by using the pybind11 API which relies mostly on
macros and compile time introspection to define the module initialization point
as well as type converters between OPAE C++ Core types and OPAE Python types.

## Benefits
The major benefits of using pybind11 for developing the OPAE Python API
include, but are not limited to, the following features of pybind11:

* Uses C++ 11 standard library although it can use C++ 14 or C++17.
* Automatic conversions of shared_ptr types
* Built-in support for numpy and Eigen numerical libraries
* Interoperable with the Python C API

## Runtime Requirements
Because opae.fpga is built on top of the opae-cxx-core API, it does require
that the runtime libraries for both opae-cxx-core and opae-c be installed on
the system (as well as any other libraries they depend on). Those libraries can
be installed using the opae-libs package (from either RPM or DEB format -
depending on your Linux distribution).

## Installation

## Python Wheels
The preferred method of installation is to use a binary wheel package for your
version of Python.

The following table lists example names for different Python versions and
platforms.

| Python Version | Python ABI      | Linux Platform | Package Name |
|----------------|-----------------|----------------|--------------|
| 2.7 | CPython w/ UCS4 | x86_64 | opae.fpga.<release>-cp27-cp27mu-linux_x86_64.whl |
| 3.4 | CPython w/ UCS4 | x86_64 | opae.fpga.<release>-cp34-cp34mu-linux_x86_64.whl |
| 3.6 | CPython w/ UCS4 | x86_64 | opae.fpga.<release>-cp36-cp36mu-linux_x86_64.whl |


opae.fpga is currently not available in the Python Package Index but once it
does become available, one should be able to install using pip by simply typing
the following:
```shell
> pip install --user opae.fpga
```

## Installing From Source
In addition to the runtime libraries mentioned above, installing from source
does require that the OPAE header files be installed as well as those header
files for pybind11. The former can be installed with the opae-devel package and
the latter can be installed by installing pybind11 Python module.

### Example Installation
The following example shows how to build from source by installing the
prerequisites before running the setup.py file.

```shell
>sudo yum install opae-libs-<release>.x86_64.rpm
>sudo yum install opae-devel-<release>.x86_64.rpm
>pip install --user pybind11
>pip install --user opae.fpga-<release>.tar.gz
```


_NOTE_: The `pip` examples above use the `--user` flag to avoid requiring root
permissions. Those packages will be installed in the user's `site-packages`
directory found in the user's `.local` directory.

## Example Scripts
The following example is an implementation of the sample, hello_fpga.c, which
is designed to configure the NLB0 diagnostic accelerator for a simple loopback.


```Python
import time
from opae import fpga

NLB0 = "d8424dc4-a4a3-c413-f89e-433683f9040b"
CTL = 0x138
CFG = 0x140
NUM_LINES = 0x130
SRC_ADDR = 0x0120
DST_ADDR = 0x0128
DSM_ADDR = 0x0110
DSM_STATUS = 0x40

def cl_align(addr):
    return addr >> 6

tokens = fpga.enumerate(type=fpga.ACCELERATOR, guid=NLB0)
assert tokens, "Could not enumerate accelerator: {}".format(NlB0)

with fpga.open(tokens[0], fpga.OPEN_SHARED) as handle:
    src = fpga.allocate_shared_buffer(handle, 4096)
    dst = fpga.allocate_shared_buffer(handle, 4096)
    dsm = fpga.allocate_shared_buffer(handle, 4096)
    handle.write_csr32(CTL, 0)
    handle.write_csr32(CTL, 1)
    handle.write_csr64(DSM_ADDR, dsm.io_address())
    handle.write_csr64(SRC_ADDR, cl_align(src.io_address())) # cacheline-aligned
    handle.write_csr64(DST_ADDR, cl_align(dst.io_address())) # cacheline-aligned
    handle.write_csr32(CFG, 0x42000)
    handle.write_csr32(NUM_LINES, 4096/64)
    handle.write_csr32(CTL, 3)
    while dsm[DSM_STATUS] & 0x1 == 0:
        time.sleep(0.001)
    handle.write_csr32(CTL, 7)

```

This example shows how one might reprogram (Partial Reconfiguration) an
accelerator on a given bus, 0x5e, using a bitstream file, m0.gbs.

```Python
from opae import fpga

BUS = 0x5e
GBS = 'm0.gbs'
tokens = fpga.enumerate(type=fpga.DEVICE, bus=BUS)
assert tokens, "Could not enumerate device on bus: {}".format(BUS)
with open(GBS, 'rb') as fd, fpga.open(tokens[0]) as device:
    device.reconfigure(0, fd)
```