pciaer.o implementation notes
=============================

implementation_notes.txt $Id: baf102f3c9caba83fa3a075ba572fa8bdec30183 $

This file applies to specification version 2.17 (6.9.2012)
and release 2.46 of the driver.

The purpose of this file is to tell you where I'm up to in implementing the
spec. so that if you're using the driver, you know what works and what doesn't.

General/installation/parameters/nodes
-------------------------------------
Up to four boards are supported by the driver, although the library currently
only supports one.

Monitor
-------
Everything described in the driver spec. is implemented.
There are currently the following differences from the spec.:

Read works more or less as documented for the non-blocking case, but will
return 0 in what should be the blocking case when there is no data to be read.
Read is presently still very inefficient, and does not use interrupts.

Without interrupt support, poll will either return immediately if data is
available or will sleep the full timeout period (or until a signal is received)
without the process waking up when data becomes available.

Sequencer
---------
Everything described in the driver spec. is implemented.
There are currently the following differences from the spec.:

Release does not yet block until the sequencer is empty. This means that closing
the sequencer currently instantly disables the sequencer and puts the FIFO in
reset, thus losing any remaining data. If this is not acceptable, the caller
should check that the FIFO is empty using the PCIAER_IOC_GET_SEQ_FIFO_FLAGS call
before closing the device.

Write works more or less as documented for the non-blocking case, but will
return 0 in what should be the blocking case when the sequencer FIFO is full.
The special behaviour required if O_SYNC is set is not yet implemented.
Write is presently still very inefficient, and does not use interrupts.

Without interrupt support, poll will either return immediately if space is
available in the FIFO for data to be written or will sleep the full timeout
period (or until a signal is received) without the process waking up when space
becomes available.

Fsync currently does nothing, though it does it successfully
(ie. returns no error)

Mapper
------
Features described in the spec. other than the following are implemented:
- PCIAER_IOC_MAP_ADD_TO_MAPPING is not yet implemented
- PCIAER_IOC_MAP_DEL_FROM_MAPPING is not yet implemented
- PCIAER_IOC_MAP_COMPACT has been temporarily subverted to provide a means of
testing the out-of-memory (OOM) handler. Currently the only effect is that the
driver's cache of the Configuration NVRAM's data is cleared making future NVRAM
data access slower.

At present the support for PCIAER_IOC_MAP_CLEAR and PCIAER_IOC_SET_MAP_MAPPING
is only rudimentary. What this means in practice is that in order to set
up the remapping table, you should first call the PCIAER_IOC_MAP_CLEAR ioctl
and then call the PCIAER_IOC_SET_MAP_MAPPING ioctl. If you make a mistake,
there is currently no way to remove mappings, except by doing
PCIAER_IOC_MAP_CLEAR and starting again.
Support for the mapping mode PCIAER_IOC_MAP_OUT_1_TO_1 has been temporarily(?)
removed.

Stress testing of reading and writing SRAM (using ../testcode/stressmap) has
revealed two possible hardware problems: (1) the 'Unreliable SRAM Write' problem
(see report Unreliable_SRAM_Write.doc) and (2) crashes, apparently on SRAM reads.
These problems need further investigation from a hardware point of view, but a
software workaround for (1) has been found and implemented.

Configuration NVRAM
-------------------
Everything described in the driver spec. is implemented.

Common ioctls
-------------
Everything described in the driver spec. is implemented.

Debugfs
-------
Everything described in the driver spec. is implemented.