README
======

This file provides a quick overview of the files in the source directory, and is
bound to be out of date.  The following applications are built:

fa-archiver
    Saves FA sniffer data to an archive and provides a socket interface for
    retrieval of the archived data.

fa-prepare
    Used to prepare the archive data area before running fa-archiver.

fa-capture
    Connects to a running archive and captures live or historical data.

python/fa-viewer.py
    Displays live FA data graphically


Make files etc
--------------

makefile
    This is the makefile invoked in response to running `make`.  This is used to
    ensure that all of the files built by this project are built out of tree in
    build subdirectory.

Makefile
    The main makefile, invoked with working directory set to ./build and with
    VPATH set to .

build
    Build directory.  This can safely be deleted.


Top level application files
---------------------------

archiver.c archiver.h
    This is the main application, the FA sniffer archiver.

capture.c
    Captures a continuous stream of sniffer data to a file.

prepare.c
    Prepares a file or volume for use as an FA sniffer archive.


Supporting components
---------------------

buffer.c buffer.h
    Circular in-memory buffer supporting one writer (sniffer) and multiple
    readers (disk_writer, socket_server).

disk.c disk.h
    Defines on disk storage.  Some of this is a relic of the obsolete facility
    for reading archive data directly from the disk.

disk_writer.c disk_writer.h
    Write archiver data directly to disk.

error.c error.h
    Common error handling macros and assocated support functions.

list.h
    Some double link list macros and inline functions derived from the kernel.

locking.c locking.h
    Simple wrappers of pthread locking routines.

mask.c mask.h
    Support routines for handling subsets of sniffer frames, and a sensible
    place for other supporting routines.

matlab.c matlab.h
    Implements writing Matlab header to data stream.

parse.c parse.h
    String parsing routines.

reader.c reader.h
    Implements read access to the FA archive.

sniffer.c sniffer.h
    Capture of sniffer data from the FA sniffer device.

socket_server.c socket_server.h
    Interface to FA sniffer clients.

timing.h
    This is not part of the project proper, but records a useful timing
    technique.

transform.c transform.h
    Processing of data read from sniffer device, reshapes data on its way to the
    archive file.


Notes on SSE
------------

Here is the SSE stuff that used to be in transform.c (see commit c30eee83 in the
pcie sniffer driver, or svn commit 50921)::

    #include <xmmintrin.h>

    /* This call is an SSE intrinsic, defined in xmmintrin.h, only enabled
     * if -msse specified on the command line.  The effect of this is to use
     * the MMX register for transferring a single FA entry, but more to the
     * point, write combining is used on the output.  This means that the
     * output block is never fetched into cache, which should significantly
     * speed up processing.
     *    Alas, the documentation for this is pretty poor.
     *
     * References include:
     *  http://lwn.net/Articles/255364/
     *      Ulrich Drepper on memory optimisation
     *  http://www.redjam.com/codeplay/documentation/intrinsics.html
     *      Lists intrinsics for another compiler
     *  http://math.nju.edu.cn/help/mathhpc/doc/intel/cc/
     *  mergedProjects/intref_cls/
     *      Documents Intel intrinsics.
     *  www.info.univ-angers.fr/~richer/ens/l3info/ao/intel_intrinsics.pdf
     *      Intel Intrinsic Reference, document 312482-003US. */
    _mm_stream_pi((__m64 *) output++, *(__m64 *) input);
    input += FA_ENTRY_COUNT;
    _mm_stream_pi((__m64 *) output++, *(__m64 *) input);
    *output ++ = *input;

    /* After performing the transpose with SSE above we have to reset the
     * floating point state as otherwise subsequent floating point arithmetic
     * will fail mysteriously. */
    _mm_empty();


Notes on work to do
-------------------

* Possibly eliminate use of `pthread_cancel` and thus simplify `LOCK` and
  `UNLOCK` macros.  Would need to either orderly shut down every thread or
  simply allow them to die on exit.

* Is it worth making the effort to close the listen socket on shutdown?
  Probably not as program exit will close it anyway.