PCI-AER board Driver, Library & Documentation

Material Transfer Agreement

If you are not a member of INI and you have obtained a PCI-AER board made at INI, you, or someone in authority in your organisation should already have signed a Material Transfer Agreement (MTA) similar to the one linked to from here. If not, then the act of downloading the source code with the intent to use it with such a board will in any case be taken as agreement to the conditions of the MTA.

This is only a means of enforcing our MTA which relates primarily to the PCI-AER board hardware made by or for INI. For all other purposes, the driver code may be freely downloaded and distributed according to the terms of the GNU Public License (GPL), version 2.

Driver & Library

The driver takes the form of a kernel module in a file called pciaer.ko, and there is a static-link library called libpciaer.a.

Latest Release in .tgz form

The latest release of the driver, library, test code and utilities can be downloaded here:

• pciaer-2.45.tgz, for Linux kernels in the 3.0 series
  (tested on Ubuntu 11.10 running kernel 3.0.0-17-generic).

Once you have downloaded the appropriate file and un-tar'ed it using tar -xzvf filename, you should just need to change into the resulting directory and type make to build everything. Note that the driver module must be compiled with the kernel version with which it is to be used.

RPM packages are no longer provided.

Using the Driver

Once the driver has been built, it must be properly installed. To install the driver, run make install (as root). You will then be able to insert and remove the driver module into/from the kernel as often as you like using

sudo /sbin/modprobe pciaer

and

sudo /sbin/modprobe -r pciaer

respectively.

Latest Source as a git Repository

Since July 2011, the sources for the driver, library, test code and utilities are being maintained in git.

If you are a member of INI, you can clone the repository from /users/amw/pciaer/pciaer.git.

If you are not a member of INI, and would like to get access to the git repository, please email me.

Change Log

Changes that are (or might be) user-visible are as follows:

• 2.45:
  • The deprecated ioctls PCIAER_IOC_READ_NVR_BYTE and PCIAER_IOC_WRITE_BYTE were removed.
  • The PCIAER_IOC_GET_STATS and PCIAER_IOC_RST_STATS ioctls are now deprecated and will be removed in the next release (along with the already deprecated PCIAER_IOC_GET_PCI_INFO). Equivalent statistics functionality is now available via debugfs, see the Driver Specification for details.
  • The Makefile infrastructure and .spec file for building RPMs has been removed.
  • make install now assumes Ubuntu rather than OpenSUSE.
  • The format in which resource information is logged has changed slightly.
  • The mapping ioctls PCIAER_IOC_SET_MAP_MAPPING, PCIAER_IOC_GET_MAP_MAPPING_COUNT, and PCIAER_IOC_GET_MAP_MAPPING now work correctly when called from 32-bit user space programs on running on 64-bit kernels without generating a log message. However, user space code should still be recompiled to create 64-bit executables to run on 64-bit systems.
• 2.44:
  • In addition to the PCIAER_IOC_GET_PCI_INFO, PCIAER_IOC_GET_STATS and PCIAER_IOC_RST_STATS ioctls, all of the mapping ioctls PCIAER_IOC_SET_MAP_MAPPING, PCIAER_IOC_GET_MAP_MAPPING_COUNT, PCIAER_IOC_GET_MAP_MAPPING, PCIAER_IOC_MAP_ADD_TO_MAPPING and PCIAER_IOC_MAP_DEL_FROM_MAPPING are explicitly not supported from 32-bit user space programs on running on 64-bit kernels. (They didn't work in this situation previously anyway). This essentially means that 32-bit user space programs can be used on 64-bit systems to control the monitor and sequencer, but not the mapper. User space code should be recompiled to create 64-bit executables to run on 64-bit systems. Offending programs will now only be logged once per run.
  • The PCIAER_IOC_GET_PCI_INFO ioctl is now deprecated. The information obtainable via this ioctl can also be obtained by inspecting sysfs in user space code - see lib/pciinfo.c for an example of how to do this. This code can be invoked using the new -l option to pciinfotest.
  • The ioctls PCIAER_IOC_READ_NVR_BYTE and PCIAER_IOC_WRITE_BYTE are now deprecated. Progams should use ordinary read and write calls on the NVRAM device instead. These read and write calls now work even in low memory situations, which was not the case previously.
  • The preprocessor symbol to define to include debug code in the driver module is now the more standard CONFIG_PCIAER_DEBUG, rather than PCIAER_DEBUG.
  • The driver no longer uses typedefs for its structures, but typedefs remain defined for user space code.
  • The memory/IO resources used by pciaer are now logged on initialization in a more standard form.
  • There is no longer a makenodes script. Run make nodes if you need to create the device nodes outside of the context of normal installation.
  • Wherever statistics are printed by the testcode, PciaerStats::operator<< now outputs a timestamp for the statistics in addition to the statistics themselves.
  • There is a new utility script s5920nvram-support/setvpdfield for setting arbitrary VPD fields in the on-board NVRAM.
  • The sources now includes a TODO file.
• 2.43: Version 2.43 is essentially the same as 2.42, just compiled on Ubuntu 10.10 for kernel 2.6.35. There are no user visible changes.
• 2.42:
  • The driver now allows the use of 32-bit user programs on 64-bit systems while emitting a warning that the user space code should be recompiled, but the ioctls PCIAER_IOC_GET_PCI_INFO, PCIAER_IOC_GET_STATS and PCIAER_IOC_RST_STATS are not supported in this situation.
  • Improved prevention of information leakage from the kernel when using the PCIAER_IOC_GET_STATS ioctl.
  • The previously deprecated _DEBUG_ ioctls have been removed. User code should be using debugfs and/or the allow_mmap_write module parameter instead.
• 2.41:
  • The driver now accesses I/O memory using the kernel's ioread32 and iowrite32 functions instead of readl and writel; this might make certain operations slower by a vanishingly tiny amount.
  • Debug access to the S5920 and Xilinx registers (e.g. as used by the fpgaregs test program) is now via debugfs; the _DEBUG_ ioctls are deprecated. In order to be able to write directly to the Mapper SRAM for debugging purposes, there is now a module parameter allow_mmap_write which allows write access to be obtained to the mmap'ed SRAM.
  • The driver now hooks into the kernel's out-of-memory (OOM) handling code and tries to release any memory it can when an OOM situation arises. This may mean that access to the NVRAM configuration data is slower after the OOM handler is run. The driver's OOM handler can also be triggered by the otherwise non-functional PCIAER_IOC_MAP_COMPACT ioctl.
  • Support for the deprecated PCIAER_IOC_GET_FIFO_DEPTH ioctl has been removed. User code should be using fstat instead.
  • The pciaercfg configuration program now implements the -a and -g options. The -g option makes it much easier to save and restore the configuration of a board from the command line.
• 2.40:
  • The Makefile now takes the path to modprobe from /proc/sys/kernel/modprobe instead of `which modprobe` to avoid 'which: no modprobe in ...' messages when make is invoked by non-root users.
  • Various minor changes relating to internal differences between kernels 2.6.23 and 2.6.31 (should be no user-visible differences).
• 2.39:
  • A debugfs directory is created, typically /sys/kernel/debug/pciaer/
  • ioctls no longer run under the BKL (Big Kernel Lock).
  • Some problems encountered compiling the test code on Ubuntu are fixed.

Hardware Prerequisites

You should make sure that your PCI-AER board is fitted with a PROM containing the following FPGA code versions:

Driver version info: {0x022D;0x4202;0x4203;0x00}

where the second and third numbers are the version numbers of FPGA1 and FPGA2 respectively. (The first number represents the version number of the driver, e.g. here 0x022D should be interpreted as 0x02.0x2D or in decimal, 2.45.)

If when using a new release of the driver you are unable to open the Monitor (/dev/aermon*) or Sequencer (/dev/aerseq*) and errno == 524, or you see a message similar to the following in /var/log/messages:

pciaer: initialization failed for board 0 with error 524

please contact me. This error indicates that the NVRAM on the board needs to be re-programmed. I can send you instructions explaining how to do this.

Adrian

Documentation

The following useful documents are available:

• Hardware user manual (Figure 2)
• IDT720x FIFO datasheet
• Driver specification
• Driver implementation notes
• Library specification
• Usage information for the pciaercfg configuration utility

Google Groups Discussion Group

The Google Groups group for discussing the PCI-AER board and related software can be found here: http://groups.google.ch/group/pci-aer

Institut für Neuroinformatik home page.