Author: Alexandru Patriciu
e-mail: apatriciu@gmail.com

This is a small interface that allows OpenCL access from OpenStack.

I tested the programs on a devstack install. The intalation folder for my configuration 
was $NOVA_DIR = /opt/stack

The interface consists of the following parts

ComputeNode:
- server side python programs
    reside in $NOVA_DIR/nova/contrib/OpenCLServer
- a shared library PyOpenCLInterface.so that exposes OpenCL to python calls.
    
Controller Node
- nova compute api-extesion
    - WSGI extension - reside in $NOVA_DIR/nova/nova/api/openstack/compute/contrib
      unit tests are in $NOVA_DIR.nova/nova/tests/api/openstack/compute/contrib
         these are not integrated yet into openstack tests but they are written 
         using pyton unittest module. The user should run the tests to ensure that
         the openCL interface is up.
    - internal OpenCL API client - reside in $NOVA_DIR/nova/nova/OpenCL
      unit tests in $NOVA_DIR/nova/nova/tests/OpenCL
         these are not integrated yet into openstack tests but they are written 
         using pyton unittest module. The user should run the tests to ensure that
         the openCL interface is up.
- python client
    python sources are in $NOVA_DIR/novaclient/v1_1/contrib
    small test programs $NOVA_DIR/novaclient/tests/v1_1/contrib

Instalation:
Step 1: Build the PyOpenCLInterface.so library;
 - go to folder ServerSidePythonOpenCLInterface
 - Set the include and lib folders to match your system in file OpenCLInterfaceSetup.py.
 - Build the shared library.

  $python OpenCLInterfaceSetup.py build

  This should create PyOpenCLInterface.so in a subfolder 'build'. 
 - Copy the shared library PyOpenCLInterface.so into the tests/ subfolder. 
  Goto subfolder tests to run the unit tests for PyOpenCLInterface.
  $cd tests
  - Build the PyTestObjects.so shared lib.
  $python TestObjectsSetup.py build
  - Copy the shared library PyTestObjects into the tests folder. 
  - Run the unit tests to ensure that the OpenCL is running properly.

Step 2: Install the Compute node components
 - go to folder InstalationScripts
 - make sure that the target folder in the script InstallServer is properly set
 $./InstallServer
 - The server is started using the script StartServer from the target directory
 - By default the server loads the amqp configuration from /etc/nova/nova.conf. If this doesn't
 correspond to your settings you have to change the StartServer script to load the proper 
 configuration file. In settings the rabbit options are under the [DEFAULT] section.
 If in your configuration the rabbit options are under Group [Rabbit] you will have to 
 change how the options are loaded.
Step3: Install the controller components
  - go to folder InstalationScripts
  - verify if the instalation directories in the script InstallControllerComponents match 
  your configuration.
  - run the script InstallControllerComponents
  Copy the python files for the resource extensions and unit tests into the nova directory structure.
  The rabbit options are loaded from the nova config file.
  You can hack and manually set them in class OpenCLRPCAPI.__init__(...)). 
Step 3: Copy the client python files into the novaclient folder.
Step 4: Run the server on the compute node
  python OpenCLServer.py
Step 5: Run the opencl unit tests in folders
  /nova/nova/tests/OpenCL/
  /nova/nova/tests/api/openstack/compute/contrib/

Step 4: Add the following environment variables on the client side describing the credentials
    OS_USERNAME
    OS_PASSWORD
    OS_AUTH_URL
    OS_TENANT_NAME

Step 5: Run the samples in TestcomputeOpenCL.

KNOWN ISSUES:
- the OpenCLServer has to be manually started
- the data transfer is curently implemented using amqp. The MemRead and Write operations should be 
implemented using Swift