home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / languages / dice_443 / dice.lzh / doc / COMPILER.DOC < prev    next >
Text File  |  1991-01-13  |  14KB  |  364 lines
  1.  
  2. compiler/compiler                        compiler/compiler
  3. compiler/COMPILER                        compiler/COMPILER
  4.  
  5.                 DICE SYSTEM
  6.  
  7.                   Matthew Dillon
  8.                   891 Regal Rd.
  9.                   Berkeley, Ca. 94708
  10.                   USA
  11.  
  12.                   dillon@overload.Berkeley.CA.US
  13.                   uunet.uu.net!overload!dillon
  14.  
  15.                   BIX: mdillon
  16.  
  17.             COMPILER FEATURES LIST AND ORGANIZATION
  18.  
  19.             NOTE: net distributed releases will not contain
  20.               commodore includes or amiga*.lib
  21.  
  22.     (1) Organization of includes and libraries, default:
  23.  
  24.     DINCLUDE:        location of top level includes such as stdio.h
  25.     DINCLUDE:Amiga/     location of amiga includes (e.g. amiga/exec/types.h)
  26.                 (amiga includes not included)
  27.  
  28.     NOTE !!! Amiga includes should be placed in the subdirectory
  29.     dinclude:Amiga, that is, dinclude:Amiga/Exec/*.h,
  30.     dinclude:Amiga/graphics/*.h, etc...
  31.  
  32.     DCC references startup and libraries to DLIB:
  33.  
  34.     DLIB:amigas.lib     A small-data model version of AMIGA.LIB
  35.     DLIB:c.lib        The main C library for which you have source code
  36.     DLIB:m.lib        The math library
  37.     DLIB:auto.lib        The auto library-open library
  38.     DLIB:c.o        The startup module
  39.     DLIB:x.o        The terminator module
  40.  
  41.     (2) Organization of includes and libraries, -2.0 option (usually
  42.     set in the DCCOPTS enviroment variable)
  43.  
  44.     DINCLUDE:AMIGA20/   instead of DINCLUDE:AMIGA
  45.     DLIB:amigas20.lib   instead of DLIB:amigas.lib
  46.  
  47.  
  48.     (3) DCC generated link lines
  49.  
  50.     If you give DICE the following line:
  51.  
  52.     1> DCC foo.o -o foo
  53.  
  54.     It will run DLink with the following options:
  55.  
  56.     DLink dlib:c.o foo.o dlib:c.lib dlib:amigas.lib dlib:auto.lib dlib:x.o -o foo
  57.  
  58.     DLIB:C.O        DICE startup code
  59.     FOO.O        your object module(s)
  60.     DLIB:C.LIB        DICE C.LIB
  61.     DLIB:AMIGAS.LIB    small data model version of commodore amiga.lib
  62.     DLIB:AUTO.LIB    DICE AUTO.LIB
  63.     DLIB:X.O        DICE section terminator code
  64.  
  65.  
  66.     Some explanation is in order.  AUTO.LIB catches any references
  67.     to common library base variables when no storage has been
  68.     declared and imports code to automatically open said libraries
  69.     on startup and close them on exit.  DICE uses this feature to
  70.     import code to open and close "dos.library" when DOSBase is
  71.     referenced, and also for the floating point libraries.
  72.  
  73.     X.O is used to supply an RTS at the end of the special autoinit
  74.     and autoexit sections.    Any module between C.O and X.O may
  75.     declare these special sections to handle run-time relocations and
  76.     other DICE features, and do so such that when the base of the
  77.     section is JSR'd all the various module's code is sequenced
  78.     through until the RTS in X.O is hit for the sections in
  79.     question.
  80.  
  81.  
  82.     (4) SMALL DATA AMIGA.LIB
  83.  
  84.     DICE uses a small-data model version of Commodore's AMIGA.LIB
  85.     to allow it to generate residentable executables (-r option to
  86.     DCC).  The small data amiga.lib, called AMIGAS.LIB (note the 's')
  87.     is generated from the large modem amiga.lib with the LIBTOS
  88.     program.
  89.  
  90.     LIBTOS, including source, is included.    The source is available
  91.     to allow developers using DICE to add new base variables to
  92.     LIBTOS's search list when new operating systems come out without
  93.     having to wait for my update.
  94.  
  95.  
  96.     ----------------------------------------------------------------------
  97.  
  98.                 COMPILER FEATURES LIST
  99.  
  100.     (0) ANSI.  Pretty much ansi.  Please report non-ansism problems.  Check
  101.     out the doc/KnownBugs list before reporting a problem.
  102.  
  103.     (1) autos are placed in registers based on weighted usage.  A0,A1,D0,D1
  104.     will be used as register variables whenever possible, which usually
  105.     reduces the number of registers that must be saved/restored in
  106.     critical low level routines.  The 'register' keyword is
  107.     essentially ignored (use 'volatile' to force a variable to NOT
  108.     be in a register).
  109.  
  110.     (2) LINK/UNLK is removed from low level routines that do not reference
  111.     A5 and do not make any subroutine calls.
  112.  
  113.     (3) MOVEM is converted to MOVE or deleted entirely when possible.
  114.  
  115.     (4) Various obvious optimizations:  use of BSET, BCLR, BTST as short
  116.     cuts to logic operations, CMP/TST, etc...
  117.  
  118.     (5) Switch() statements are optimized as follows:
  119.  
  120.         * if the range of values is less than double the number of cases
  121.           a lookup table will be used
  122.  
  123.         * if a small number of cases exists a sub[q]/beq sequence
  124.           will be used
  125.  
  126.         * for a sufficiently large set of cases that cannot be made
  127.           into a jump table, a binary subdivision method is used.
  128.  
  129.     (6) Branch optimization.  Bxx to BRAs are optimized (up to 20 hops) by
  130.     DAS, and massive optimization is done to multi-level conditionals
  131.     by the main compiler pass.
  132.  
  133.     (7) Workbench support.  The standard startup module supports the workbench.
  134.     Specifically, the low level _main() in c.o does this.
  135.  
  136.     When a program is run from the workbench, a different entry point is
  137.     called:     wbmain(wbmsg)
  138.  
  139.     If you do not supply a wbmain() then the one from the c.lib library
  140.     is used which immediately return(-1)s, exiting the program.
  141.  
  142.     The standard return from wbmain() or using exit() automatically
  143.     ReplyMsg()s the workbench message for you.
  144.  
  145.     (8) _main() shortcut for extremely low level programs.
  146.  
  147.     You may overide c.lib's _main with your own.  If you do so you may
  148.     not use any c.lib memory allocation, stdio, or fd (open,close...)
  149.     related routines.  The startup module (c.o) will still run
  150.     autoinits, autoexits, setup resident programs, and initialize your
  151.     BSS space.
  152.  
  153.     _main(len, arg)     (as passed to the program on startup)
  154.     long len;
  155.     char *arg;
  156.     {
  157.     }
  158.  
  159.     If running from the workbench, you must GetMsg() and process the
  160.     workbench startup message yourself, as well return the message
  161.     when you exit.
  162.  
  163.     _exit exists in c.o and cannot be overridden.  If you use the _main
  164.     override you may NOT call exit() unless you also override it.
  165.     Calling exit() will generate references to stdio library code and
  166.     bring it in from the library, making your executable larger
  167.     unnecessarily.
  168.  
  169.     i.e. if you use _main() you should either fall through or use
  170.     _exit() to exit.
  171.  
  172.     (9) AutoInit support.  You may qualify a subroutine with the __autoinit
  173.     keyword that will cause it to be automatically called by the
  174.     startup code rather than having to explicitly call it from main.
  175.  
  176.     This feature is more useful to bring code in indirectly.  For
  177.     example, to automatically OpenLibrary() (& CloseLibrary()) floating
  178.     point libraries if their base variables are referenced.
  179.  
  180.     Refer to the auto.lib source code for examples.
  181.  
  182.     __autoexit works the same way.    Note that __autoinit routines are
  183.     called BEFORE _main, just after autoinit libraries are openned,
  184.     and __autoexit routines are called in __exit just before autoinit
  185.     libraries are closed.
  186.  
  187.     (10) DCC runs fast.  Make everything resident and watch it fly.  Most
  188.      of this speed comes from loading entire files into memory at once.
  189.      This might present a memory problem, but in general DICE's memory
  190.      usage is comparable to Lattice and Aztec.
  191.  
  192.     (11) CODE SIZE is comparable with Lattice and Aztec, even better in
  193.      many cases.  The minimum program sizes are as follows:
  194.  
  195.     _main() { }          448    no stdio/fd
  196.      main() { }         2736    some stdio
  197.      main() { printf..} 5492    most of stdio
  198.  
  199.     (12) EXTENSIONS , see EXTENSIONS.DOC.  DICE provides many extensions
  200.      to C to support various AMIGAisms and ROM based code, including
  201.      special treatment of the 'const' storage qualifier.
  202.  
  203.     (13) The preprocessor is able to handle arbitrarily sized macros.  There
  204.      are no limits to symbol or macro length.  The preprocessor is able to
  205.      handle up to 64 levels of includes / macro recursions with arbitrary
  206.      use of the string-ize (#) and token pasting (##) operators.
  207.  
  208.      The preprocessor implements the __BASE_FILE__ macro as well as all
  209.      standard ANSI macros (__FILE__, __LINE__, __DATE__, __TIME__, ...)
  210.  
  211.     (14) DICE supports the creation of residentable executables in nearly
  212.      all cases (exception: using the __geta4 procedure qualifier
  213.      precludes being able to make an executable resident, also non
  214.      const __chip data).
  215.  
  216.      Not only is residentability supported, but it is supported
  217.      without requiring the programmer to #include all sorts of
  218.      prototype/pragma files.
  219.  
  220.     (15) DICE supports the small-data model, large data model, small and
  221.      large code models, and special data models (word absolute,
  222.      absolute known address) for supporting ROMable code.  The linker
  223.      automatically generates JMP tables when the small-code model is
  224.      used in large executables.
  225.  
  226.     (16) REGISTERED user's DICE supports __chip, __near, and __far keywords,
  227.      as well as others.
  228.  
  229.     (17) Simplified library and startup module design.  There are no multiple
  230.      versions of a single library for different memory models and the
  231.      frontend, DCC, makes all library and startup module interaction
  232.      except m.lib invisible.  The same c.o handles both resident and
  233.      non-resident startup.    c.lib and m.lib may be used with programs
  234.      that declare more than 64KBytes of BSS (though not with programs
  235.      that declare more than 64KBytes of __near initialized storage).
  236.  
  237.      There is no large-data-model version of c.lib and m.lib,
  238.      although you can easily recompile the libraries into a large-data
  239.      model version if you wish.  I suggest that instead of doing that
  240.      you stick with the small-data model and use the __geta4 type
  241.      qualifier to procedures which are called out of context.
  242.  
  243.     (18) Optimization of args to prototyped routines
  244.  
  245.  
  246.     --------------------------------------------------------------------------
  247.                     GOALS
  248.  
  249.     In writing DICE my goals are as follows:
  250.  
  251.     - reasonably fast compilation.  Modular executables for ease of use,
  252.       reliability, and testability.
  253.  
  254.     - concentrate more on reliability and less on optimizations.  Remember that
  255.       this is only the third major distribution of DICE, I expect some bugs
  256.       to show up.  I expect to become more reliable than the two other
  257.       commercial C compilers in the Amiga market within a year.
  258.  
  259.     - but do not forget optimizations... put in relatively easy to implement
  260.       optimizations that do not destroy the reliability of DICE.  DICE does
  261.       no common sub-expression or loop unrolling optimizations, but does do
  262.       relatively smart register allocation and multi-level history to
  263.       propogate conditional expressions.
  264.  
  265.     - provide comprehensive support of the Amiga, especially for new
  266.       versions of the OS that come out.
  267.  
  268.     - I have always torn my hair out at not being able to easily fix bugs in
  269.       the support libraries for commercial compilers.  DICE includes full
  270.       source for its support libraries (c.lib, m.lib, auto.lib) and a means
  271.       to remake the library.  DICE also includes full source to some of
  272.       its own utilities, namely LIBTOS and the DCC frontend which are the
  273.       most likely candidates for programmer hair loss.
  274.  
  275.     ------------------------------------------------------------------------
  276.                    COMMENTS
  277.  
  278.     Registerized parameters are not implemented.  While such a feature
  279.     would make an executable somewhat smaller and a little faster, a few
  280.     percent of gain is not worth the complexity of the implementation (and
  281.     thus the possibility of introduced bugs).  The difference in execution
  282.     speed is generally so miniscule that it isn't noticable, and where it
  283.     is noticable it is usually due to a badly implemented algorithm in
  284.     the first place.
  285.  
  286.     So, cute, but not as much of a boost as you might think.
  287.  
  288.     Inline library calls are not implemented either.  Inline library calls
  289.     are actually useful and when properly implemented increase efficiency
  290.     to low level calls such as AddHead() and GetMsg().  Other calls such as
  291.     Move() and Draw() do not increase noticably in efficiency. #pragma's
  292.     must be used to define inline calls and this makes the compiler
  293.     enviroment less portable.  Lattice made a big mistake *requiring* the
  294.     use of inline library calls with residentable programs.  My solution
  295.     was to write a program to convert AMIGA.LIB into a small-data version
  296.     of same called AMIGAS.LIB.
  297.  
  298.     In general, I refuse to implement a thousand nearly useless features
  299.     that will only introduce more bugs into the compiler.
  300.  
  301.     ------------------------------------------------------------------------
  302.                 COMPATIBILITY
  303.  
  304.                    ANSI C
  305.  
  306.     DICE is getting closer to being ANSI C compliant, there are only a
  307.     few things missing.
  308.  
  309.     I spent a great deal of time ensuring that STDIO routines run relatively
  310.     fast.  I decided to write nearly all of the support library in C instead
  311.     of falling back to optimized assembly to keep the system uniform and
  312.     portable.  One does not notice much of a difference between the C
  313.     strcpy() and an assembly strcpy() relative to the run time of their
  314.     program.
  315.  
  316.                     AMIGA
  317.  
  318.     As said in feature (7), if you wish your program to be runnable from
  319.     the workbench you must supply a wbmain() entry point.  If you do not
  320.     then running the program from the workbench will result in its
  321.     immediate termination (e.g. nothing happens).  On return from wbmain()
  322.     or exit() the workbench message is automatically ReplyMsg()d by the
  323.     exit code.
  324.  
  325.     DICE separates workbench startup and puts it in the hands of the user
  326.     to simplify the user's code.  Since there are two entry points,
  327.     main() for CLI run programs and wbmain() for WORKBENCH-run programs,
  328.     the programmer can more easily modularize his code.
  329.  
  330.     The Registered release of DICE supports the __near, __far, and __chip
  331.     keywords.
  332.  
  333.                   UNBUFFERED CONSOLE IO
  334.  
  335.     You may set a console to RAW mode using the setbuf() and setvbuf() calls.
  336.     You may set a console back to COOKED mode using the same calls.
  337.  
  338.     ------------------------------------------------------------------------
  339.  
  340.                 Your first program
  341.  
  342.     1> cd examples
  343.     1> dcc hello.c -o ram:hello
  344.     1> ram:hello
  345.     hello world
  346.     1>
  347.  
  348.                 Your first residentable program
  349.  
  350.     1> cd examples
  351.     1> dcc hello.c -o ram:hello -r
  352.     1> ram:hello
  353.     hello world
  354.     1> resident ram:hello
  355.     1> hello        ; instantanious execution
  356.     hello world
  357.     1>
  358.  
  359.     * NOTE, a common problem is that users have removed various floating
  360.     point libraries from LIBS: and this will prevent DC1 from running.
  361.     Make sure you have the full complement of floating point libraries
  362.     in LIBS:
  363.  
  364.