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.44.tgz, for Linux 2.6 kernels in the 2.6.31 series
  (tested on SuSE 11.2 running kernel 2.6.31.14-0.8-desktop).

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.

Using the Driver

Once the driver has been built, it must be properly installed. To install the driver, run make install (you will need to be root to do this). As root, you will then be able to insert and remove the driver module into/from the kernel as often as you like by typing modprobe pciaer or modprobe -r pciaer respectively. If you are not root, you should ask your system administrator to perform the make install step and to allow you to run modprobe via sudo (*). The commands for inserting and removing the driver module as a non-root user will then be

sudo /sbin/modprobe pciaer

and

sudo /sbin/modprobe -r pciaer

respectively.

Binary RPMs

There are also binary RPMs available for openSUSE 11.2 Linux kernels which install the driver, library, header files and pciaercfg utility and create the required entries in the sudoers file:

If you are a member of INI using a standard INI machine running SuSE 11.2, you can install an appropriate rpm via the normal iniswinstall mechanism.

NB: If you install the rpm for SuSE 11.2, it's important that you use the desktop flavour of kernel rather than for instance the one called default.

Latest Source as a git Repository

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

If you are a member of INI, you can read from the repository at /users/amw/pciaer/pciaer.git. (The CVS repository at /share/src/cvsroot should no longer be used, and will be removed in the near future.)

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.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: {0x022C;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 0x022C should be interpreted as 0x02.0x2C or in decimal, 2.44.)

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 which can only be done by root. If you are a member of INI, I will do this re-programming for you. If you are not a member of INI, I will send you instructions explaining how to do it.

Adrian

(*) Note for system administrators

The entries to allow non-root users to insert and remove the module can be added to the sudoers file by running make instsudo in the driver directory.

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.