Added software API documentation

Author: www

API/.gitignore

@@ -0,0 +1,2 @@
+_build
+

API/README.md

@@ -0,0 +1,11 @@
+# PHANTOM Linux Userland IP Interface
+
+This documentation describes the interface that software applications in the PHANTOM Linux distribution can use to interact with IP cores that are programmed on the FPGA.
+
+
+
+## Building
+
+To build the documentation you should first install [Sphinx](http://www.sphinx-doc.org/en/stable/). Then execute:
+
+    ./build.sh

API/build.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+sphinx-build -M latexpdf . _build
+
+cp _build/latex/PHANTOM.pdf ./phantom_software_ip_api.pdf

API/conf.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+
+extensions = ['sphinx.ext.autodoc']
+
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+
+# General information about the project.
+project = 'PHANTOM Linux API'
+copyright = '2017, Ian Gray'
+author = 'University of York'
+
+
+version = '1.0'
+release = '1.0'
+language = None
+
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+primary_domain = "c"
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+html_theme_options = {}
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PHANTOMdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    'papersize': 'a4paper',
+    'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'PHANTOM.tex', 'PHANTOM Documentation',
+     'University of York', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'phantom', 'PHANTOM Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'PHANTOM', 'PHANTOM Documentation',
+     author, 'PHANTOM', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+

API/index.rst

@@ -0,0 +1,20 @@
+.. PHANTOM documentation master file, created by
+   sphinx-quickstart on Thu May  4 10:49:08 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+PHANTOM API
+=================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ipcores
+
+.. Indices and tables
+	==================
+
+	* :ref:`genindex`
+	* :ref:`search`

API/ipcores.rst

@@ -0,0 +1,237 @@
+Accessing IP Cores from Linux
+=============================
+
+PHANTOM FPGA IP cores are accessed by Linux userland software through the following API.
+
+
+Common Definitions
+------------------------
+
+.. macro:: PHANTOM_OK
+
+	Returned by functions to indicate no error.
+
+.. macro:: PHANTOM_FALSE
+	
+	Returned by functions to indicate false.
+
+.. macro:: PHANTOM_ERROR
+
+	Returned by functions to indicate an otherwise unspecified error.
+
+.. macro:: PHANTOM_NOT_FOUND
+
+	Returned by functions to indicate something was not found.
+
+.. type:: phantom_data_t
+
+	A type guaranteed to be wide enough to store an entire word. On Zynq systems this is `uint32_t`, and on a Zynq UltraScale+ device it is `uint64_t`.
+
+.. type:: phantom_address_t
+
+	A type guaranteed to be wide enough to store an entire system address. On Zynq systems this is `uint32_t`, and on a Zynq UltraScale+ device it is `uint64_t`.
+
+.. macro:: PHANTOM_DMA_TO_IP
+
+	Specify a DMA transfer from main memory into an IP core.
+
+.. macro:: PHANTOM_DMA_FROM_IP
+	
+	Specify a DMA transfer from an IP core's address space into main memory.
+
+
+
+Configuring the FPGA
+---------------------
+
+.. function:: int phantom_fpga_is_done()
+
+	Check the FPGA's `done` pin, which is asserted when the FPGA is successfully programmed with a bitfile.
+
+	:return: 
+		* :macro:`PHANTOM_OK` if the FPGA has been configured with a compatible bitfile
+		* :macro:`PHANTOM_FALSE` if the DONE pin is not asserted. 
+
+
+.. function:: int phantom_fpga_configure(FILE *bitfile)
+
+	Configure the FPGA fabric with the specified bitfile. bitfile is a configuration file as generated by the Xilinx tools for the appropriate FPGA part. This function assumes that the FPGA is not currently programmed. Note that this function does not block until programming is complete. :func:`phantom_fpga_is_done()` should be called to determine that programming has completed successfully before the FPGA is used.
+
+	:param FILE* bitfile: A FILE pointer to a compatible bitfile, opened in binary mode.
+
+	:return: 
+		* :macro:`PHANTOM_OK` if configuration started successfully
+		* :macro:`PHANTOM_ERROR` if the bitfile could not be sent to the FPGA.
+
+
+
+The `phantom_ip_t` structure
+----------------------------
+
+The PHANTOM IP cores in the current design are represented by instances of the `phantom_ip_t` structure which are obtained by calling :func:`phantom_fpga_get_ips()`.
+
+
+.. type:: typedef struct {...} phantom_ip_t; 
+
+The structure contains at least the following members:
+
+.. member:: char *idstring
+
+	An identifying string.
+
+.. member:: uint32_t id
+
+	A unique identifier for the IP.
+
+.. member:: uint8_t num_masters
+
+	The number of AXI Masters in the IP.
+
+.. member:: phantom_address_t base_address
+
+	The base memory address of the IP core's AXI Slave.
+
+.. member:: phantom_address_t address_size
+
+	The size in bytes on the IP core's AXI Slave memory space.
+
+.. 
+
+
+Reading IP Core Information
+--------------------------- 
+
+.. function:: int phantom_fpga_get_num_ips()
+
+	If the FPGA is currently programmed, this gives the number of PHANTOM IP cores in the current design.
+
+	:return: the number of IP cores that are currently configured onto the FPGA. -1 if a problem is encountered.
+
+
+.. function:: phantom_ip_t *phantom_fpga_get_ips()
+
+	If the FPGA is currently programmed, this fetches an array of `phantom_ip_t` that describe the PHANTOM IP cores in the design, as in the following example::
+
+		phantom_ip_t *ips = phantom_fpga_get_ips();
+
+		for(int i = 0; i < phantom_fpga_get_num_ips(); i++) {
+			printf("%d: %s\n", i, ips[i].idstring);
+		}
+
+	:return: An array of the PHANTOM IPs in the currently-programmed design, or `NULL` if none exist.
+
+
+.. function:: int phantom_fpga_ip_initialise(phantom_ip_t *ip, const char *idstring)
+
+	If the FPGA is currently programmed, search for the PHANTOM IP core with the provided `idstring`. The `ip` struct is then initialised. 
+
+	:param phantom_ip_t* ip: A `phantom_ip_t` struct to be initialised.
+	:param char* idstring: The identifier string of the IP.
+	
+	:return: 
+		* :macro:`PHANTOM_OK` if the IP is successfully initialised.
+		* :macro:`PHANTOM_NOT_FOUND` if the FPGA is correctly programmed, but the requested core cannot be found. 
+		* :macro:`PHANTOM_ERROR` if another error occurs.
+
+
+.. function:: int phantom_fpga_ip_initialise_by_id(phantom_ip_t *ip, uint32_t id)
+
+	As :func:`phantom_fpga_ip_initialise()`, but initialises a core based on its unique id. This is useful for when multiple copies of the same IP core are present. These can be queried through the use of :func:`phantom_fpga_get_ips()`.
+
+	:param phantom_ip_t* ip: A `phantom_ip_t` struct to be initialised.
+	:param uint32_t id: The unique identifier of the IP.
+	
+	:return: 
+		* :macro:`PHANTOM_OK` if the IP is successfully initialised.
+		* :macro:`PHANTOM_NOT_FOUND` if the FPGA is correctly programmed, but the requested core cannot be found. 
+		* :macro:`PHANTOM_ERROR` if another error occurs.
+
+
+
+
+
+
+
+IP Control
+----------
+
+.. function:: int phantom_fpga_ip_start(phantom_ip_t* ip)
+	
+	Starts the specified IP. Has no effect if the core is already started.
+
+	:param phantom_ip_t* ip: The IP core to control.
+
+	:return: :macro:`PHANTOM_OK` if the core started successfully, or :macro:`PHANTOM_ERROR` if not.
+
+
+.. function:: int phantom_fpga_ip_is_done(phantom_ip_t* ip)
+	
+	Checks if the specified IP has completed its execution.
+
+	:param phantom_ip_t* ip: The IP core to query.
+
+	:return: :macro:`PHANTOM_OK` if the core stopped successfully, or :macro:`PHANTOM_FALSE` if not.
+
+
+.. function:: int phantom_fpga_ip_is_idle(phantom_ip_t* ip)
+	
+	Checks if the specified IP is idle and ready for I/O or to be started.
+
+	:param phantom_ip_t* ip: The IP core to query.
+
+	:return: :macro:`PHANTOM_OK` if the core is idle, or :macro:`PHANTOM_FALSE` if not.
+
+
+
+
+IP Data I/O
+-----------
+
+PHANTOM IPs are presented to the Linux kernel as Userland IO (UIO) devices, and so the entire address space can be mapped and accessed using simple get and set functions. This is not the most efficient way to move large volumes of data however. The IP core itself can read and write from main system memory through an AXI master interface. Therefore the UIO interface should be used to pass parameters and configuration data, and the device itself should fetch input data as required using AXI burst transfers.
+
+It is also possible for the hardware design to include an AXI DMA controller to support automatic bulk data movement. This core can be controlled through the UIO interface through the simple helper functions provided here. More complex DMA transfers can be coded directly.
+
+
+.. function:: int phantom_fpga_ip_set(phantom_ip_t* ip, phantom_address_t addr, phantom_data_t val)
+	
+	Set a value inside the AXI Slave address space of the IP. `addr` is based from 0 and will be automatically offset to the appropriate base address (`phantom_ip_t.base_address`).
+
+	:param phantom_ip_t* ip: The IP core to query.
+	:param phantom_address_t addr: The address, based at 0, inside the address space of the IP core.
+	:param phantom_data_t val: The value to set.
+
+	:return: :macro:`PHANTOM_OK` if the value was set, or :macro:`PHANTOM_ERROR` if not.
+
+
+.. function:: phantom_data_t phantom_fpga_ip_get(phantom_ip_t* ip, phantom_address_t addr)
+	
+	Get a value from the AXI Slave address space of the IP. `addr` is based from 0 and will be automatically offset to the appropriate base address (`phantom_ip_t.base_address`).
+
+	:param phantom_ip_t* ip: The IP core to query.
+	:param phantom_address_t addr: The address, based at 0, inside the address space of the IP core.
+
+	:return: The value of the argument specified by `addr`.
+
+
+.. function:: int phantom_fpga_dma_transfer(phantom_ip_t* ip, phantom_address_t dma_core, phantom_address_t buffaddr, phantom_address_t length, int direction)
+
+	Cause a DMA core in the specified IP core to initiate a DMA transfer. This function assumes that an AXI DMA IP core is located at the appropriate address in the memory space of the target IP. This function returns immediately and the transfer will begin a time after this. For more details consult the Xilinx DMA Core driver.
+
+	:param phantom_ip_t* ip: The IP core to query.
+	:param phantom_address_t dma_core: The offset, starting at 0, of the DMA core inside the address space of the IP.
+	:param phantom_address_t buffaddr: The address in main memory to start the transfer from.
+	:param phantom_address_t length: The length in bytes of the transfer.
+	:param int direction: The direction of the transfer. Valid values are `PHANTOM_DMA_TO_IP` or `PHANTOM_DMA_FROM_IP`
+
+	:return: :macro:`PHANTOM_OK` if the transfer was started, or :macro:`PHANTOM_FALSE` if not.
+
+
+.. function:: int phantom_fpga_dma_is_idle(phantom_ip_t* ip, phantom_address_t dma_core, int direction)
+
+	Check if the DMA core in the specified IP core is idle in the given direction. Because the Xilinx AXI DMA core is bidirectional, it is possible for a transfer to be proceeding in one direction whilst the other is idle.
+
+	:param phantom_ip_t* ip: The IP core to query.
+	:param phantom_address_t dma_core: The offset, starting at 0, of the DMA core inside the address space of the IP.
+	:param int direction: The direction of the transfer. Valid values are `PHANTOM_DMA_TO_IP` or `PHANTOM_DMA_FROM_IP`
+
+	:return: :macro:`PHANTOM_OK` if the core is idle, or :macro:`PHANTOM_FALSE` if not.