f-cpu/c/README.txt
created Sat Jul  6 23:19:39 CEST 2002 by whygee@f-cpu.org


If you follow F-CPU's adventures for a while, you have certainly
remarked that what newbies ask most, after a decent website, is
a software "simulator/emulator" that allows them to develop F-CPU
programs. There is also the need for a compiler but that's another
story.

YG's position is that there is no need for a simulator written in C because
 1) it's ugly (i know, i tried it with QDCPOC last year)
 2) the VHDL sources do the trick already (use vanilla or Simili
    with the provided scripts and you're done)
 3) duplicating the source code (having different versions in different
    langages) is a high risk : the sources will become incoherent
    very quickly if the C and VHDL teams don't synchronize all the time.
 4) all the precedent attemps were very badly written and fall into 3)

The usual answers are :
 A) C is faster than VHDL
    --> FPGA are faster and ncsim or riviera are very fast simulators.
        OTOH, people say that speed is not an issue. dumb.
 B) people do not want to mess with VHDL and simulators
    --> they are simply lazy to read the VHDL-HOWTO !

What they want is a pre-chewed piece of "sexy" C code that will
do the same work as Bochs. I am very worried with 3) and 4) and
there are great chances that someone else will do "yet another crapy F-CPU
instruction set simulator" that will not be as flexible as the VHDL
version and (worse) will not correspond to the RTL/behavioural sources.
On top of that, FreeHDL provides an interesting alternative but
doesn't work at all : it would take more effort to hack into FreeHDL
than writing a simulator from scratch. Bad luck.

There is a solution, however, but you will have to forget about your
hopes for dirty C hacks ! If you want your work to be useful and last
longer than a few weeks, you have to follow the rest of the flock.
If the simulator code is not as flexible as the VHDL sources, it will
not be maintained anyway.

                    ---------oO0Oo---------

Here is the methodology :

 - exclusive use of the provided library located in f-cpu/include
   --> if something is not present, create the corresponding file(s)
       under f-cpu/configuration
   --> all data types and definitions must be configurable with the
       existing configuration scripts.
 - a subdirectory is created : f-cpu/c which contains a hierarchy
   similar to f-cpu/vhdl. All EUs have their own directory.
 - The same methodology is applied as in VHDL : individual tests !
    * One file contains the EU behaviour
    * Another file contains the testbench
    * Because it's C, there's a header file for the EU which contains
      the local variables (definitions #MUST# be located in
      f-cpu/include and/or f-cpu/configuration !)
    * A script will run the testbench on the EU in C and VHDL and
      compare the results. If they don't match, the unit is not considered
      as valid.
    * Don't forget the README's !

                    ---------oO0Oo---------

As of july 2002, this method has only started. All the EUs must be
rewritten in C and tested against their VHDL models. However, i wish
that when other units are added, the C version will be only a small
overhead.

The whole simulator will obviously be finished roughly at the same
time as the VHDL version, which can be a long time. However you will
have the warm fuzzy satisfaction that :
 - it corresponds exactly to the VHDL model
 - it runs faster (or so one believes)
 - it's a #clean# and scalable code that will not be forgotten next year.

#################################################################

Rememeber that F-CPU is a deadly serious project.
Don't get trapped inside C's idioms and apparent ease,
because the source will loose it's extensibility and
portability. Instead, think in terms of the function the source
must perform and the underlying algorithm. Don't sacrifice
this methodology for speed or features. The algorithm matters
more than the way it is implemented, so don't cripple the
algorithm because it would run faster. It can ALWAYS run
faster anyway and i could have written this in assembly
langage. You wouldn't want to read asm code, don't you ?
And if it was hyper-optimised, how would one verify that all
the units work exactly as expected ?

#################################################################

In a sense, this side of the project is a "clean" version of
QDCPOC where all the lessons are taken into account. If you don't
follow the method, you'll fall into the same problems as QDCPOC.
 
  ( QDCPOC means "Quick and Dirty Coded Proof Of Concept"
    and was a little prototype for a C simulator written
    by YG in summer 2001 to test some scheduling concepts)

It uses the same clocking method, it's a cycle-acurate and has the
same features as the VHDL sources. The only difference is that
it is written in reasonably clean C, that's all.
