Add README.md to the project

README.md

@@ -0,0 +1,115 @@
+# Zynq AXIS: A complete DMA system
+
+This repo contains all the components needed to set up a DMA based project
+using the Zynq FPGA from Xilinx. First there is a hardware module called AXIS
+that connects to a high performance AXI interface port. Second, there is a
+Linux UIO Driver that exposes the low level AXIS control hardware to the Linux
+userspace. Third is a userspace library that takes the low level driver
+interface and provides a more application friendly interface for the user.
+Lastly there are some example applications to demonstrate the use of the above
+components.
+
+
+## Hardware
+
+HDL code is kept in the *hdl* directory, separate from the Xilinx Vivado
+project directories to make it easier to share code between projects and also
+to upgrade Xilinx tool versions as needed.
+
+To synthesize the bitstream file one must have the Vivado tools installed and
+sourced, then simply run the "syn-proj" script from this repos root directory.
+
+``` bash
+./syn-proj
+```
+
+If there is more then one Xilinx project in the *syn* directory, pass the
+projects name as an argument into the syn-proj script to chose it. A bash
+completion script can be found in the *util* directory to make working with
+this repos scripts easier.
+
+
+## Linux UIO Driver
+
+This Linux driver has been developed to run on the Xilinx Zynq ARM. It is a
+userspace input/output driver (UIO) that enables the passing of register values
+to and from the Zynq FPGA. Userspace libraries/applications use this UIO driver
+to configure and control the AXIS modules operation. It also controls a
+contiguous memory area that is used to pass data between the host (PS) and FPGA
+(PL) sides of the Zynq.
+
+### Compile Driver
+
+Kernel modules need to be built against the version of the kernel it will be
+inserted in. It is recommended to uses the Linux kernel maintained by Xilinx.
+
+``` bash
+git clone https://github.com/Xilinx/linux-xlnx.git
+```
+
+The driver module can be compiling outside of the Linux kernel source tree. A
+variable 'KDIR' in the Makefile is used to point to the kernel source
+directory. The default value has it pointing to the default Linux install
+location for kernel sources. However, if cross compiling or if the sources are
+in a non-default location the value can be overridden using an exported
+environmental variable or as an argument passes into the make command.
+
+```bash
+cd zynq-axis/dev/
+export KDIR=../../linux-xlnx
+make
+```
+
+or
+
+```bash
+cd zynq-axis/dev/
+make KDIR=../../linux-xlnx
+```
+
+### Installing Driver
+
+Use of the driver module requires it to be inserted into the running Linux
+kernel. Once inserted it will automatically create a character device file in
+'/dev' called '/dev/uio*'. However, the default permissions will not allow
+non-root users to read/write to the file, nor is the numbering consistent if
+more then one UIO driver is being used. These problems are overcome by
+installing the udev rule file found in this projects *util* directory into the
+systems '/etc/udev/rules.d/' directory.
+
+```bash
+sudo cp util/80-axis.rules /etc/udev/rules.d/
+```
+
+To install the module and have it loaded at boot, first install the udev rule
+as shown above and then follow the below instructions.
+
+```bash
+sudo mkdir -p /lib/modules/$(uname -r)/extra/
+sudo cp axis.ko /lib/modules/$(uname -r)/extra/
+sudo depmod -a
+sudo modprobe axis
+```
+
+
+## Library
+
+The axis library has to be built and installed on the Zynq before the example
+applications can be compiled. The library offers a number of generic functions
+for use in configuring the axis hardware.
+
+```bash
+cd lib/
+make
+make install
+```
+
+
+## Applications
+
+The example application demonstrates some simple usage of the AXIS system.
+
+```bash
+cd app/
+make
+```