
(This documentation is related to the development of gf2x)

This src/ subdirectory is the place where new code may be added to gf2x,
in particular new code for lowlevel routines, so-called mul1, mul2, mul3,
and so on. The steps for adding code are:

* Choose a file name. Assuming you are coding a new version of mul3, for
  instance, you might choose to name your file mul3foo.c. The file name
  must match mul[0-9] because probably some scripts rely on it.

* Write a skeleton for mul3foo.c based on pre-existing files. There are a
  couple of very important things in writing this file:
  - The file must be guarded by a #ifndef GF2X_MUL3_H_ / ... / #endif
    construct. The name of the macro matters.
  - The file must include gf2x-small.h
  - The function included must be called gf2x_mul3, and match the
    expected prototype.

* For inserting this function in the tuning mechanism, edit Makefile.am ;
  Since the tedious Makefile.am code is now generated by a perl script
  (albeit not automatically), one just has to add a new line among those
  starting with #*
  Then, to regenerate the tedious section of Makefile.am, do:
    perl -i ./generate-test-list.pl Makefile.am
  Note that this edits Makefile.am in place, so you'd better quit your
  text editing section on Makefil.am first.

Generated code:

It is more complicated to add a new code _generation_ mechanism, and
requires the following steps.

* Assuming the generator code is in C (but it does not matter much), then
  it must be codded, and a rule for building the _generator_ must be
  added to Makefile.am. There is not much to it, probably a matter of
  adding only a simple line to Makefile.am

* Your generator must accept arguments, and output its result to a file
  whose name matches gen_mul3 (for a mul3 of course). Or possibly write
  to stdout. Then you have to copy one of the very ugly paragraphs, e.g.
  the one for tune_gen_mul1_w64k2. The same warnings as above apply.

* The generation rule has to be told to generate-test-list.pl somehow.
