Authors: Richard Brent, Pierrick Gaudry, Emmanuel Thomé, Paul Zimmermann.
License:
 GNU general Public License (version 2 or any later version).

This package contains routines for fast arithmetic in GF(2)[x]
(multiplication, squaring, gcd).

Summary:
========

This README covers:

 - Package contents
 - Caution for gcc users
 - Instructions to install the package
 - Caution regarding installation
 - Hooking gf2x into ntl
 - Using the library


Package contents:
=================

It contains the following files:

Miscellaneous doc files:

README
BUGS
src/TODO
src/README
already_tuned/tuned/README
AUTHORS
ChangeLog

Actual code:

gf2x.h                 - main api
gf2x-impl.h            - internal api
gf2x.c                 - top-level source for multiplication code
gf2x-small.h           - small-sized inlined multiplication routines
toom.c                 - main file for Karatsuba and Toom-Cook multiplication
fft.c                  - multiplication using Fast Fourier Transform
ntl_gf2x_mul_code.h    - file to be hooked in NTL (see below)

Code adapted for the selected hardware

already_tuned/              - pre-configured codes for selected architectures.
already_tuned/*/gf2x-thresholds.h - pre-tuned thresholds files
already_tuned/generic/gf2x-thresholds.h - placeholder thresholds
already_tuned/generic64/    - code that works on any 64-bit platform
already_tuned/generic32/    - code that works on any 32-bit platform
already_tuned/x86_64/       - code that works on amd64 and intel core2
already_tuned/x86_sse2/     - code that works on x86 platforms supporting sse2
already_tuned/generic/      - code that works everywhere. Does _not_ include mul1

gf2x/                  - place where symlinks to the files above go

For testing:

tests/check-mul.c       - simple check program
tests/check-mul.res     - reference results from check-mul
tests/do-check-mul.sh   - shell script driving check-mul

For tuning:

src/mul*.c              - various candidate code samples for basic routines
src/tuneup.c            - tuning program for basecase multiplication
src/tunetoom.c          - tuning program for Karatsuba/Toom-Cook multiplication
src/tunefft.c           - tuning program for FFT multiplication
src/tune-lowlevel.pl

src/gen_bb_mul_code.c   - program to generate many alternatives for mul1
src/replace.h           - helper code
src/replace.c           - helper code
src/tuning-common.h     - helper code
src/tuning-common.c     - helper code
src/timing.h            - helper code
src/timing.c            - helper code
src/update-thresholds.c - helper code

Applications that use gf2x and NTL. These applications are covered by the
GPL.

apps/halfgcd.hpp - subquadratic gcd over GF(2)[x]
apps/halfgcd.cpp - subquadratic gcd over GF(2)[x]
apps/factor.cpp  - finds smallest irreducible factor of trinomial over GF(2)
apps/check*.sh   - some tests using factor

Caution for gcc users:
======================

gcc versions 4.3.0 and 4.3.1 have a bug which affects gf2x in a an
unpredictable way. It is recommended to upgrade to at least 4.3.2, or
configure with --disable-sse2

Instructions to install the package:
====================================

Cautious users follow steps 1 to 5 below. Urged users follow only 1 and 5.

1) Type:

      ./configure && make

   A special case: your hardware platform may support several ABIs
   (Application Binary Interfaces), corresponding to the type ``unsigned
   long'' being either 32-bit or 64-bit wide. The gf2x package
   accomodates for this under the assumption that ABI selection is
   covered by the selection of the appropriate compiler options. In order
   to compile for an ABI different from the default one, you have to pass
   additional parameters to the configure script:

      ./configure ABI=<bit width of unsigned long> CFLAGS=<corresponding CFLAGS> && make

   For example on a Mac OS X computer with an Intel Core 2 processor
   using gcc, one may use: ./configure ABI=64 CFLAGS="-O2 -m64" && make

   (equivalently, one may also use ABI=64 CC='gcc -m64')

   Several other flags and arguments can be passed to ./configure (or set
   as environment variables) ; see ./configure --help

2) Highly recommended ; run

      make check

   To guard against possible bugs (either from gf2x or from the
   compiler).

3) Optional, but recommended: tune low-level routines, Karatsuba/Toom-Cook and
   FFT multiplication:

      make tune-lowlevel
      make tune-toom
      make tune-fft

   Note that there are some minor issues related to tuning on amd64 -- see BUGS.

   Tuning unfortunately takes a long while ; it is possible to decrease
   the time spent in tuning using additional parameters to the ``make
   tune-*'' commands, more specifically:
      make tune-toom TOOM_TUNING_LIMIT=<max size in words>
      make tune-fft FFT_TUNING_LIMIT=<max size in words>
   The default values for TOOM_TUNING_LIMIT and FFT_TUNING_LIMIT are 2048
   and 8000000, respectively. TOOM_TUNING_LIMIT must be in the range [30,2048],
   while FFT_TUNING_LIMIT is only limited by the available memory.

   More detailed information on tuning can be found in the
   src/tunetoom.c and src/tunefft.c files, as well as
   src/README.

   All the tuning targets automatically rebuild the library in order to
   incorporate the tuned parameters. So an additional ``make'' is
   unnecessary (although innocuous, since the library should be up to
   date).

4) Highly recommended ; run

      make check

   to see whether everything went ok.

5) Either run:

      make install

   Or, if you prefer, keep your build tree, and have your programs
   include <buildtree>/gf2x.h, and link against the library
   <buildtree>/.libs/libgf2x.a (static) or <buildtree>/.libs/libgf2x.so
   (dynamic). Usual pitfalls apply regarding dynamic linking: if you are
   familiar with none of the "-Wl,-rpath,<path>" or "LD_LIBRARY_PATH"
   ways of making this work, your easiest bet is to stick to the static
   library approach.

Caution regarding installation:
===============================

The header files installed in $includedir/gf2x/ are architecure-dependent.

Hooking gf2x into ntl:
======================

ntl-5.5 offers the possibility to replace the multiplication of
polynomials with the gf2x code. For this, you have to install the gf2x
library in your favorite /path/to/gf2x/ (e.g. using gf2x's ./configure
--prefix=/path/to/gf2x/ && make && make install). Then configure NTL with

./configure NTL_GF2X_LIB=on GF2X_PREFIX=/path/to/gf2x/

If for some reason gf2x was installed with custom directories, you may
also consider the GF2X_INCDIR and GF2X_LIBDIR options ; some setups will
typically require GF2X_LIBDIR=/path/to/gf2x/lib64, for example.

For version 5.4.2 of ntl, you have the possibility of patching an NTL
tree with gf2x. For this, do the following.

- untar ntl-5.4.2 in /path/to/ntl-5.4.2
- build gf2x: cd /path/to/gf2x ; ./configure ; make
- from the gf2x source tree, run ./inject-ntl-5.4.2 /path/to/ntl-5.4.2
- cd /path/to/ntl-5.4.2 ; make && make check

Using the library:
==================

gf2x exports one public header called gf2x.h . This header exports one
function gf2x_mul, whose use is documented in gf2x.h . Note that gf2x_mul
is not reentrant, so if you need a reentrant version, prefer gf2x_mul_r
which uses an externally allocated storage pool.

Some ``half-public'' headers are in the gf2x/ subdirectory. Some of these
headers (gf2x/gf2x-thresholds.h and gf2x/gf2x_mul* are
architecture-dependent). In order to use the inlined multiplication
routines for small sizes, you may use gf2x/gf2x-small.h.

By default, gf2x creates both static and dynamic libraries.