f-cpu/config/README.txt
created Sun Aug 19 06:34:18 by whygee@f-cpu.org

This directory contains the necessary files that generate
the .h include files and VHDL packages that contains
the critical constants. This way, a single set of file
is necessary to define all the constants in all different
langages.

The .m4 files contain the definitions of all specified
"values", which are then inserted in the apropriate files.
The original files are suffixed with ".in" to distinguish
between the "real" files and the common definitions.
These original files and the output files must not be
modified by the end-user in the general case.

All the definitions start with "__DEF_" and end with
the name of the variable that is really being defined,
to avoid further confusion.

Strategy : The preprocessing is performed in two passes,
thanks to m4's -F and -R features.
 * the first pass parses all the definitions which are then
   written ("-F" option) to the langage_c.m4f and
   langage_vhdl.m4f files.
 * the second pass retrieves ("-R" option) the m4f file
   corresponding to the apropriate langage and then
   perform the keyword substitutions.
This two-passes strategy does not require to append "dnl"
after every definition and comment in the m4 files,
and it accelerates a bit the repetitive task of gathering
the definitions.

Langages : each langage has a specific small file which is
parsed before the other definition files, during the first pass.
This way, adding Verilog support (for example) will not
require the modification of the main .m4 definition files.

Note : computing values is performed inside m4 files,
with the function "m4_eval()". The target langage is thus 
meaningless and we don't have to care about the syntax of
the operators (ie: '|' doesn't need to be replaced by
'or' in VHDL files).

Comments : the m4 files is parsed with the -F option
and the output of the first pass is sent to /dev/null
so all the "clear" text in *.m4 is meaningless, it's like comments.
To avoid the last chances of confusion and side effects,
the "--prefix-builtins" option prefixes all m4's builtin functions
with "m4_". If you run into problems, seek strings containing
"m4_" and read the m4 info files.

When customizing the F-CPU core for end-user applications,
it is recommended to limit the modifications to "f-cpu_user.m4".
More features and options will be pregressively added
in the future.
