[BACK]Return to gforth.ds CVS log [TXT] [DIR] Up to [gforth] / gforth / doc

Diff for /gforth/doc/gforth.ds between versions 1.52 and 1.53

version 1.52, 2000/06/11 11:06:25 version 1.53, 2000/06/12 19:38:26
Line 6268  the top of stack, which is not reflected Line 6268  the top of stack, which is not reflected
 the convention that I use and recommend (it clashes a bit with using  the convention that I use and recommend (it clashes a bit with using
 locals declarations for stack effect specification, though).  locals declarations for stack effect specification, though).
   
   @menu
   * CREATE..DOES> applications::  
   * CREATE..DOES> details::       
   * Advanced does> usage::        
   @end menu
   
   @node CREATE..DOES> applications, CREATE..DOES> details, User-defined Defining Words, User-defined Defining Words
 @subsubsection Applications of @code{CREATE..DOES>}  @subsubsection Applications of @code{CREATE..DOES>}
 @cindex @code{CREATE} ... @code{DOES>}, applications  @cindex @code{CREATE} ... @code{DOES>}, applications
   
Line 6314  DOES> ( n2 -- n1+n2 ) Line 6321  DOES> ( n2 -- n1+n2 )
 -2 curry+ 2-  -2 curry+ 2-
 @end example  @end example
   
   @node CREATE..DOES> details, Advanced does> usage, CREATE..DOES> applications, User-defined Defining Words
 @subsubsection The gory details of @code{CREATE..DOES>}  @subsubsection The gory details of @code{CREATE..DOES>}
 @cindex @code{CREATE} ... @code{DOES>}, details  @cindex @code{CREATE} ... @code{DOES>}, details
   
Line 6369  CREATE name EXECUTE ( ... -- ... ) Line 6377  CREATE name EXECUTE ( ... -- ... )
     @i{initialization}      @i{initialization}
 @end example  @end example
   
   
 doc->body  doc->body
   
   @node Advanced does> usage,  , CREATE..DOES> details, User-defined Defining Words
   @subsubsection Advanced does> usage
   
   
   
 @node Deferred words, Aliases, User-defined Defining Words, Defining Words  @node Deferred words, Aliases, User-defined Defining Words, Defining Words
 @subsection Deferred words  @subsection Deferred words
Line 8541  doc-break" Line 8552  doc-break"
 @cindex code words  @cindex code words
   
 @menu  @menu
 * Common Assembler::              * Code and ;code::              
   * Common Assembler::            Assembler Syntax
 * Common Disassembler::           * Common Disassembler::         
 * 386 Assembler::               Deviations and special cases  * 386 Assembler::               Deviations and special cases
 * Alpha Assembler::             Deviations and special cases  * Alpha Assembler::             Deviations and special cases
 * MIPS assembler::              Deviations and special cases  * MIPS assembler::              Deviations and special cases
   * Other assemblers::            How to write them
 @end menu  @end menu
   
 @node Common Assembler, Common Disassembler, Assembler and Code Words, Assembler and Code Words  @node Code and ;code, Common Assembler, Assembler and Code Words, Assembler and Code Words
 @subsection Common Assembler  @subsection @code{Code} and @code{;code}
   
 Gforth provides some words for defining primitives (words written in  Gforth provides some words for defining primitives (words written in
 machine code), and for defining the machine-code equivalent of  machine code), and for defining the machine-code equivalent of
Line 8583  The typical usage of these @code{code} w Line 8596  The typical usage of these @code{code} w
 analogy to the equivalent high-level defining words:  analogy to the equivalent high-level defining words:
   
 @example  @example
 : foo                                        code foo  : foo                              code foo
    <high-level Forth words>                        <assembler>     <high-level Forth words>              <assembler>
 ;                                            end-code  ;                                  end-code
                                   
 : bar                                        : bar  : bar                              : bar
    <high-level Forth words>                     <high-level Forth words>     <high-level Forth words>           <high-level Forth words>
    CREATE                                       CREATE     CREATE                             CREATE
       <high-level Forth words>                     <high-level Forth words>        <high-level Forth words>           <high-level Forth words>
    DOES>                                        ;code     DOES>                              ;code
       <high-level Forth words>                     <assembler>        <high-level Forth words>           <assembler>
 ;                                            end-code  ;                                  end-code
 @end example  @end example
   
 @code{flush-icache} is always present. The other words are rarely used  @code{flush-icache} is always present. The other words are rarely used
Line 8641  Generation}). Defining words (equivalent Line 8654  Generation}). Defining words (equivalent
 defined words) may require changes in @file{engine.c}, @file{kernel.fs},  defined words) may require changes in @file{engine.c}, @file{kernel.fs},
 @file{prims2x.fs}, and possibly @file{cross.fs}.  @file{prims2x.fs}, and possibly @file{cross.fs}.
   
   @node Common Assembler, Common Disassembler, Code and ;code, Assembler and Code Words
   @subsection Common Assembler
   
   The assemblers in Gforth generally use a postfix syntax, i.e., the
   instruction name follows the operands.
   
   The operands are passed in the usual order (the same that is used in the
   manual of the architecture).  Since they all are Forth words, they have
   to be separated by spaces; you can also use Forth words to compute the
   operands.
   
   The instruction names usually end with a @code{,}.  This makes it easier
   to visually separate instructions if you put several of them on one
   line; it also avoids shadowing other Forth words (e.g., @code{and}).
   
   Control flow is specified similar to normal Forth code (@pxref{Arbitrary
   control structures}), with @code{if,}, @code{ahead,}, @code{then,},
   @code{begin,}, @code{until,}, @code{again,}, @code{cs-roll},
   @code{cs-pick}, @code{else,}, @code{while,}, and @code{repeat,}.  The
   conditions are specified in a way specific to each assembler.
   
 @node  Common Disassembler, 386 Assembler, Common Assembler, Assembler and Code Words  @node  Common Disassembler, 386 Assembler, Common Assembler, Assembler and Code Words
 @subsection Common Disassembler  @subsection Common Disassembler
   
Line 8651  doc-disasm Line 8685  doc-disasm
   
 The disassembler generally produces output that can be fed into the  The disassembler generally produces output that can be fed into the
 assembler (i.e., same syntax, etc.).  It also includes additional  assembler (i.e., same syntax, etc.).  It also includes additional
 information in comments.  information in comments.  In particular, the address of the instruction
   is given in a comment before the instruction.
   
   @code{See} may display more or less than the actual code of the word,
   because the recognition of the end of the code is unreliable.  You can
   use @code{disasm} if it did not display enough.  It may display more, if
   the code word is not immediately followed by a named word.  If you have
   something else there, you can follow the word with @code{align last @ ,}
   to ensure that the end is recognized.
   
 @node 386 Assembler, Alpha Assembler, Common Disassembler, Assembler and Code Words  @node 386 Assembler, Alpha Assembler, Common Disassembler, Assembler and Code Words
 @subsection 386 Assembler  @subsection 386 Assembler
Line 8662  Andrew McKewan; it is in the public doma Line 8704  Andrew McKewan; it is in the public doma
 @node Alpha Assembler, MIPS assembler, 386 Assembler, Assembler and Code Words  @node Alpha Assembler, MIPS assembler, 386 Assembler, Assembler and Code Words
 @subsection Alpha Assembler  @subsection Alpha Assembler
   
 The Alpha assembler and disassembler were written by Bernd Thallner.  The Alpha assembler and disassembler was written by Bernd Thallner.
   
 @node MIPS assembler,  , Alpha Assembler, Assembler and Code Words  @node MIPS assembler, Other assemblers, Alpha Assembler, Assembler and Code Words
 @subsection MIPS assembler  @subsection MIPS assembler
   
 The MIPS assembler was originally written by Christian Pirker.  The MIPS assembler was originally written by Christian Pirker.
Line 8687  If the architecture manual specifies sev Line 8729  If the architecture manual specifies sev
 arguments (i.e., two for @code{jalr,}).  When in doubt, see  arguments (i.e., two for @code{jalr,}).  When in doubt, see
 @code{arch/mips/testasm.fs} for an example of correct use.  @code{arch/mips/testasm.fs} for an example of correct use.
   
 Branches in the MIPS architecture have a delay slot.  You have to fill  Branches and jumps in the MIPS architecture have a delay slot.  You have
 it yourself (the simplest way is to use @code{nop,}), the assembler does  to fill it yourself (the simplest way is to use @code{nop,}), the
 not do it for you (unlike @command{as}).  Even @code{if,},  assembler does not do it for you (unlike @command{as}).  Even
 @code{ahead,}, @code{until,}, @code{again,} and @code{while,} need a  @code{if,}, @code{ahead,}, @code{until,}, @code{again,}, @code{while,},
 delay slot.  For the branches produced by @code{else,} and  @code{else,} and @code{repeat,} need a delay slot.  Since @code{begin,}
 @code{repeat,}, an @code{nop,} is in the delay slot.  and @code{then,} just specify branch targets, they are not affected.
   
   Note that you must not put branches, jumps, or @code{li,} into the delay
   slot: @code{li,} may expand to several instructions, and control flow
   instructions may not be put into the branch delay slot in any case.
   
 For branches the argument specifying the target is a relative address;  For branches the argument specifying the target is a relative address;
 You have to add the address of the delay slot to get the absolute  You have to add the address of the delay slot to get the absolute
 address.  address.
   
   The MIPS architecture also has load delay slots and restrictions on
   using @code{mfhi,} and @code{mflo,}; you have to order the instructions
   yourself to satisfy these restrictions, the assembler does not do it for
   you.
   
   You can specify the conditions for @code{if,} etc. by taking a
   conditional branch and leaving away the @code{b} at the start and the
   @code{,} at the end.  E.g.,
   
   @example
   4 5 eq if,
     ... \ do something if $4 equals $5
   then,
   @end example
   
   @node Other assemblers,  , MIPS assembler, Assembler and Code Words
   @subsection Other assemblers
   
   If you want to contribute another assembler/disassembler, please contact
   us (@email{bug-gforth@@gnu.org}) to check if we have such an assembler
   already.  If you are writing them from scratch, please use a similar
   syntax style as the one we use (i.e., postfix, commas at the end of the
   instruction names, @pxref{Common Assembler}); make the output of the
   disassembler be valid input for the assembler, and keep the style
   similar to the style we used.
   
   Hints on implementation: The most important part is to have a good test
   suite that contains all instructions.  Once you have that, the rest is
   easy.  For actual coding you can take a look at
   @file{arch/mips/disasm.fs} to get some ideas on how to use data for both
   the assembler and disassembler, avoiding redundancy and some potential
   bugs.  You can also look at that file (and @pxref{Advanced does> usage})
   to get ideas how to factor a disassembler.
   
 @c -------------------------------------------------------------  @c -------------------------------------------------------------
 @node Threading Words, Locals, Assembler and Code Words, Words  @node Threading Words, Locals, Assembler and Code Words, Words
 @section Threading Words  @section Threading Words
Removed from v.1.52  
changed lines
  Added in v.1.53

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>