kernel-module-datra: Linux driver module for Datra


DESCRIPTION

This module forms the link between the Datra IP in programmable logic and
userspace programs. The "libdatra" interface further wraps the driver
interface, and is strongly recommended. The driver can be used "as is"
though, see kernel-module-datra.txt for a description of the /dev/ tree
it creates and how to use it.


BUILDING

Build this module like any other. If you are using OpenEmbedded or Yocto,
simply use the "kernel-module-datra.bb" recipe to build and deploy it.

If you have your own cross-compilation environment, have it set up the usual
environments for make, in particular $CC and $CFLAGS, and set $KERNEL_SRC
to point at the development sources for your kernel. The provided makefile
will then build the modules named "datra*.ko".

It is also possible to integrate the module into the kernel directly. This
requires adapting Kconfig and makefiles in the kernel accordingly.

To install on a local machine, just run:
  make
  sudo make modules_install
# if that fails, just do the following:
  sudo cp *.ko /lib/modules/$(uname -r)/extra/
  sudo depmod -A


CONFIGURATION

On PCIe, no configuration is required, any PCIe card with Datra on it
will automatically trigger loading the datra-pcie driver.
However, the generated device files will not have the right permissions by 
default. To fix this, copy the datra.rules file to the /etc/udev/rules.d folder.
Keep in mind that this is an 'example' rules file that gives everybody access.

On embedded platforms like the Zynq, the module requires a devicetree
entry. Add a snippet like the following to your dts file:

&fpga_axi {
	datra@64400000 {
		compatible = "topic,datra-1.00.a";
		reg = <0x64400000 0x200000>;
		interrupt-parent = <&gic>;
		interrupts = <0 57 0x4>;
	};
};

In this snippet, Datra will be using memory address 0x64400000 on the
AXI bus, and a total of 1MB (0x20000) address space. The interrupt is
set to 89 (which is 57+32) and must be of the "level" type (0x04).
These settings must match what was programmed into the IP in the PL
(the DDE connects the Datra IP interrupt by default at pin 89).
If the address is wrong, this will likely result in bus errors or even
system lockup when the module loads. If the IRQ is incorrect, the driver
will load and appear to function , but data transfers will fail to
function correctly.