home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / forth / compiler / fpc / tcomintf.doc < prev    next >
Text File  |  1991-04-26  |  13KB  |  317 lines
  1. \ TCOMINTF.SEQ    This file documents the TCOM compiler target interface
  2.  
  3.   The TCOM compiler can compile code only if it knows how to compile
  4. into your target.  The following defered words (in COMPILER.SEQ) provide
  5. a mechanism for linking your target into the compiler.  In many cases,
  6. you can use leave the default assigned functions in place, and implement
  7. only those needed by your target.  Of the fifty or so defered words
  8. listed here, only the 24 marked "***REQUIRED***" actually MUST be
  9. implemented for most targets.  Others will need to be implimented for
  10. targets that have special characteristics.
  11.  
  12. Word Name       Default Func   Compile Stack
  13. ---------------------------------------------------------------------------
  14. !-T                %!-T          ( n taddr -- )
  15.         Stores a word into the target in low byte to low address, high
  16.         byte to high address order.  You will only need to change this
  17.         for target processors that use a different type, order or size
  18.         address or data.
  19.  
  20. %T"                %%T"          ( a1 -- )
  21.         Compiles a string into target data memory. Will need to be
  22.         changed if your target keeps its fixed data like string in an
  23.         address space other than where it keeps its variables.  Typically
  24.         you will need to change this if you are making a ROM system since
  25.         strings will normally be in ROM not RAM.
  26.  
  27. ,"                 %%T,"         ( | string" -- )
  28.         Compiles a string into target data memory. See also the note for
  29.         %T".
  30.  
  31. ,-T                %,-T          ( n -- )
  32.         Compile the worn "n" into the target.  See also the note for !-T.
  33.  
  34. .ALIST             %.ALIST       ( -- )
  35.         Display the additional help messages added by the ALIST.SEQ file.
  36.  
  37. .ASYMBOL           %.ASYMBOL     ( a1 -- )
  38.         Display the symbol a1. Used by the /CODE and /SHOW options to
  39.         display symbols to the user as they are defined.
  40.  
  41. ?.#DIS             %?.#DIS       ( a1 n1 -- )
  42.         Display disassembled instructions n1 starting at target address
  43.         a1 if the /CODE option has been used. Part of ALIST.SEQ
  44.  
  45. ?.CALL             %?.CALL       ( a1 -- )
  46.         Display symbol a1 in the form CALL <name> if the /CODE option
  47.         has been used.
  48.  
  49. ?.MACRO            %?.MACRO      ( a1 -- )
  50.         Display symbol a1 in the form --M-- <name> if the /CODE option
  51.         has been used.
  52.  
  53. @-T                %@-T          ( a1 -- n1 )
  54.         Fetch a word from the target. See also !-T.
  55.  
  56. COMP_CALL          %COMP_CALL    ( a1 -- )
  57.         ***REQUIRED***
  58.         This function compiles a CALL to the target function specified by
  59.         the symbol address a1.
  60.  
  61. COMP_DECR          DECR          ( -- )
  62.         ***REQUIRED***
  63.         Compiles the code required to decrement the contents of an
  64.         address on the stack. DECR must either be a MACRO, or a F-PC
  65.         Forth word that uses RES_COMP_CALL if DECR is a CODE word. See
  66.         the following:
  67.  
  68.         MACROs are installed in the COMP_ type functions as follows:
  69.  
  70.                 MACRO DECR      ( a1 -- )
  71.                                 ...
  72.                                 END-MACRO
  73.  
  74.                 ' DECR >EXECUTE IS COMP_DECR
  75.  
  76.         Terget words in TCOM have two code fields, the first code field
  77.         (the own returned by ') is used while interpreting, and the
  78.         second code field (at >EXECUTE) is used when compiling.
  79.  
  80.         If DECR were a CODE word instead of a MACRO, then you would need
  81.         to make a definition like this:
  82.  
  83.                 CODE DECR       ( a1 -- )
  84.                                 ...
  85.                                 RET     END-CODE
  86.  
  87.                 >FORTH FORTH
  88.                 : xDECR         ( -- )
  89.                                 F['] DECR RES_COMP_CALL ;
  90.                 ' XDECR IS COMP_DECR
  91.                 TARGET >TARGET
  92.  
  93.         This creates a Forth definition that the compile will execute.
  94.         Its function is to compile a CALL to DECR, and make sure DECR
  95.         gets resolved in the target.
  96.  
  97. COMP_FETCH         @             ( -- )
  98.         ***REQUIRED***
  99.         Compiles the code required to fetch the contents of an address
  100.         on the stack.  See also the note for DECR.
  101.  
  102. COMP_FPUSH         FPUSH         ( -- )
  103.         ***REQUIRED***
  104.         Only required if you are trying to support floating point in your
  105.         target. If you aren't using floating point, just don't try to use
  106.         FCONSTANT.
  107.  
  108.  
  109.  
  110.  
  111. COMP_INCR          INCR          ( -- )
  112.         ***REQUIRED***
  113.         Compiles the code required to increment the contents of an
  114.         address on the stack.  See also the note for DECR.
  115.  
  116. COMP_JMP_IMM       %COMP_JMP_IMM ( a1 -- )
  117.         ***REQUIRED***
  118.         A Forth word that compiles the code required to jump to the
  119.         address a1 on the stack.  a1 is not a symbol, but an actual
  120.         target address.
  121.  
  122. COMP_OFF           OFF           ( -- )
  123.         ***REQUIRED***
  124.         Compiles the code required to set the contents of an address
  125.         on the stack to zero.  See also the note for DECR.
  126.  
  127. COMP_ON            ON            ( -- )
  128.         ***REQUIRED***
  129.         Compiles the code required to set the contents of an address
  130.         on the stack to $FFFF.  See also the note for DECR.
  131.  
  132. COMP_PERFORM       PERFORM       ( -- )
  133.         ***REQUIRED***
  134.         Compiles the code required to do a "FETCH EXECUTE" of the address
  135.         on the stack.  See also the note for DECR.
  136.  
  137. COMP_PSTORE        +!            ( -- )
  138.         ***REQUIRED***
  139.         Compiles the code required to do a plus-store to the contents of
  140.         an address on the stack with the value under the address.  See
  141.         also the note for DECR.
  142.  
  143. COMP_REST          %R>REST       ( -- )
  144.         ***REQUIRED***
  145.         Compiles the code required to store the top value of the RETURN
  146.         STACK into the contents of an address on the stack. See also the
  147.         note for DECR. Used by RESTORE>
  148.  
  149. COMP_SAVE          %SAVE>R       ( -- )
  150.         ***REQUIRED***
  151.         Compiles the code required to save the contents of the address on
  152.         the stack to the RETURN STACK. See also the note for DECR.
  153.         Used by SAVE>
  154.  
  155. COMP_SAVEST        %SAVE!>R      ( -- )
  156.         ***REQUIRED***
  157.         Compiles the code required to save the contents of the address on
  158.         the stack to the RETURN STACK, and then store the second item on
  159.         the stack into the address. See also the note for DECR.
  160.         Used by SAVE!>
  161.  
  162. COMP_SINGLE        (LIT)         ( -- )
  163.         ***REQUIRED***
  164.         Compiles the code required to push a literal value onto the
  165.         stack. See also the note for DECR.
  166.  
  167. COMP_STORE         !             ( -- )
  168.         ***REQUIRED***
  169.         Compiles the code required to store into the contents of an
  170.         address on the stack, the second item on the stack.  See also
  171.         the note for DECR.
  172.  
  173. END-L:             %END-L:       ( -- )
  174.         ***REQUIRED***
  175.         A Forth word that performs whatever is needed for this target to
  176.         end a library COLON definition.
  177.  
  178. END-LCODE          %END-LCODE    ( -- )
  179.         ***REQUIRED***
  180.         A Forth word that does whatever is needed to end a library CODE
  181.         word.
  182.  
  183. END-LM:            %END-LM:      ( -- )
  184.         ***REQUIRED***
  185.         A Forth word that does whatever is needed to end a library MACRO
  186.         COLON word.  M: words are like normal COLON definitions except
  187.         they are layed inline, like a MACRO whereever they are used.
  188.  
  189. END-MACRO          %END-MACRO    ( -- )
  190.         ***REQUIRED***
  191.         A forth word that does whatever is needed to end a MACRO.
  192.  
  193. END-T:             %END-T:       ( -- )
  194.         ***REQUIRED***
  195.         A Forth word that does whatever is needed to end a COLON
  196.         definition.
  197.  
  198. LCODE-START        %LCODE-START  ( -- )
  199.         ***REQUIRED***
  200.         A Forth word that does whatever is needed to start a library CODE
  201.         definition.  Typically selecting the assembler vocabulary, and
  202.         performing any assembler initialization needed.
  203.  
  204. MACRO-START        %MACRO-START  ( -- )
  205.         ***REQUIRED***
  206.         A Forth word that does whatever is needed to start a MACRO.  See
  207.         also LCODE-START.
  208.  
  209. RESOLVE_1          %RESOLVE_1    ( A1 -- )
  210.         Resolves address a1 to here in the target, as relative.  If your
  211.         branches are absolute, or byte oriented, then you will need to
  212.         re-define this word.
  213.  
  214. SAVE-IMAGE.COM     %SAVE-IMAGE.COM ( | -- )
  215.         Save the current memory image after comping is complete, to disk
  216.         in a binary format.  You can re-define this to your liking if you
  217.         have a special disk file format you need.  A file HEXSAVE.SEQ
  218.         will save the image in a format very similar to Intel Hex format.
  219.  
  220.  
  221. SET_COLD_ENTRY     %SET_COLD_ENTRY ( -- )
  222.         A Forth word that sets the COLD entry vector in the target to
  223.         point (relative) to here of the target.  used to mark each new
  224.         COLON definition as the entry point of the program.
  225.  
  226. START-T:           NOOP          ( -- )
  227.         A Forth word that does whatever is needed to start a COLON
  228.         definition.
  229.  
  230. SUB_RET            %SUB_RET      ( -- )
  231.         ***REQUIRED***
  232.         A Forth word that backs up as many bytes is needed to UNASSEMBLE
  233.         the RET just compiled for the current COLON definition.  In an
  234.         indirect threaded target, this would be something like
  235.         "-2 ALLOT-T".  In a subroutine threaded target like the 8086,
  236.         this is "-1 ALLOT-T".
  237.  
  238. TARGET-FINISH      NOOP          ( -- )
  239.         A Forth word that does whtever cleanup is required after a
  240.         compile is completed.
  241.  
  242. TARGET-INITIALIZE  TARGET-INIT   ( -- )
  243.         A Forth word that performs whatever initialization is needed for
  244.         the target. This will usually include things like setting the
  245.         default target origin for code and data, and compiling any needed
  246.         assembly code needed to initialize the target stacks and other
  247.         things.
  248.  
  249. TCODE-START        %TCODE-START  ( -- )
  250.         A Forth word that does whatever is needed to start a CODE word.
  251.  
  252. C!-T               %C!-T         ( char taddr -- )
  253.         A Forth word that stores a character into the target. See also
  254.         the description for !-T.
  255.  
  256. C,-T               %C,-T         ( char -- )
  257.         A Forth word that compiles a character into the target. See also
  258.         the description for !-T.
  259.  
  260. C@-T               %C@-T         ( taddr -- char )
  261.         A Forth word that fetches a character from the target. See also
  262.         the description for !-T.
  263.  
  264. COMP_HEADER        DROP          ( a1 -- )
  265.         A Forth word that compiles a terget HEADER for the symbol a1.
  266.         Invoked when the /HEADER option is used.
  267.  
  268. DATA-SEG-FIX       %DATA-SEG-FIX ( -- )
  269.         A Special fixup word for the 8086, that adjusts a special piece
  270.         of code in the 8086 startup to point to where the DATA segment
  271.         will be when the program is later run from DOS.  Probably not
  272.         needed for other targets.
  273.  
  274.  
  275.  
  276. FLOAT_POP          ????          ( -- ? )
  277.         Used by FCONSTANT to get a floating point number off of the
  278.         floating point stack at COMPILING time in preperation for
  279.         compiling a target floating point constant.  Probably only useful
  280.         on the 8086 target.
  281.  
  282. FOR_DOES>          %FOR_DOES>    ( a1 -- )
  283.         A Forth word that causes the proper code to be compiled into the
  284.         target when you use the form:
  285.  
  286.                 @> name         -- OR --        123 !> name
  287.  
  288.         Emulates the functionality provided by the forward operators in
  289.         F-PC, but in TCOM a literal value is compiled, followed by a
  290.         fetch, or a store.
  291.  
  292. LINE-DONE          NOOP          ( -- )
  293.         A Forth word that is invoked at the end of each source line
  294.         processed. Useful when creating listing files.
  295.  
  296. SYMFOOTER          %SYMFOOTER    ( -- )
  297.         A Forth word that writes the footer or end portion to the symbol
  298.         file after compiling is complete. Currently writes a Control-Z to
  299.         the symbol file to be compatible with the Brand-X debugger.
  300.         Invoked only if /SYM is used.
  301.  
  302. SYMHEADER          %SYMHEADER    ( -- )
  303.         A Forth word that writes the header or beginning portion to the
  304.         symbol file before compiling starts. Currently does nothing.
  305.         Invoked only if /SYM is used.
  306.  
  307. SYMWRITE           %SYMWRITE     ( A1 -- A1 )
  308.         A Forth word that writes the target symbol a1 to the symbol file.
  309.         You only need to change this if you change the symbol file
  310.         format. Invoked only if /SYM is used.
  311.  
  312. TVERSION           TVER          ( -- )
  313.         A Forth word that displaies the current target library version
  314.         number.
  315.  
  316.  
  317.