Annotation of gforth/prim, revision 1.73

1.1       anton       1: \ Gforth primitives
                      2: 
1.62      anton       3: \ Copyright (C) 1995,1996,1997,1998,2000 Free Software Foundation, Inc.
1.1       anton       4: 
                      5: \ This file is part of Gforth.
                      6: 
                      7: \ Gforth is free software; you can redistribute it and/or
                      8: \ modify it under the terms of the GNU General Public License
                      9: \ as published by the Free Software Foundation; either version 2
                     10: \ of the License, or (at your option) any later version.
                     11: 
                     12: \ This program is distributed in the hope that it will be useful,
                     13: \ but WITHOUT ANY WARRANTY; without even the implied warranty of
                     14: \ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
                     15: \ GNU General Public License for more details.
                     16: 
                     17: \ You should have received a copy of the GNU General Public License
                     18: \ along with this program; if not, write to the Free Software
1.63      anton      19: \ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
1.1       anton      20: 
                     21: 
                     22: \ WARNING: This file is processed by m4. Make sure your identifiers
                     23: \ don't collide with m4's (e.g. by undefining them).
                     24: \ 
                     25: \ 
                     26: \ 
                     27: \ This file contains primitive specifications in the following format:
                     28: \ 
1.47      anton      29: \ forth name   ( stack effect )        category        [pronunciation]
1.1       anton      30: \ [""glossary entry""]
                     31: \ C code
                     32: \ [:
                     33: \ Forth code]
                     34: \ 
1.47      anton      35: \ Note: Fields in brackets are optional.  Word specifications have to
                     36: \ be separated by at least one empty line
1.1       anton      37: \
                     38: \ Both pronounciation and stack items (in the stack effect) must
1.48      anton      39: \ conform to the C identifier syntax or the C compiler will complain.
                     40: \ If you don't have a pronounciation field, the Forth name is used,
                     41: \ and has to conform to the C identifier syntax.
1.1       anton      42: \ 
                     43: \ These specifications are automatically translated into C-code for the
                     44: \ interpreter and into some other files. I hope that your C compiler has
                     45: \ decent optimization, otherwise the automatically generated code will
                     46: \ be somewhat slow. The Forth version of the code is included for manual
                     47: \ compilers, so they will need to compile only the important words.
                     48: \ 
                     49: \ Note that stack pointer adjustment is performed according to stack
                     50: \ effect by automatically generated code and NEXT is automatically
                     51: \ appended to the C code. Also, you can use the names in the stack
                     52: \ effect in the C code. Stack access is automatic. One exception: if
                     53: \ your code does not fall through, the results are not stored into the
                     54: \ stack. Use different names on both sides of the '--', if you change a
                     55: \ value (some stores to the stack are optimized away).
                     56: \ 
                     57: \ 
                     58: \ 
                     59: \ The stack variables have the following types:
                     60: \ 
                     61: \ name matches type
                     62: \ f.*          Bool
                     63: \ c.*          Char
                     64: \ [nw].*               Cell
                     65: \ u.*          UCell
                     66: \ d.*          DCell
                     67: \ ud.*         UDCell
                     68: \ r.*          Float
                     69: \ a_.*         Cell *
                     70: \ c_.*         Char *
                     71: \ f_.*         Float *
                     72: \ df_.*                DFloat *
                     73: \ sf_.*                SFloat *
                     74: \ xt.*         XT
                     75: \ f83name.*    F83Name *
1.67      anton      76: 
                     77: \E get-current prefixes set-current
                     78: \E 
                     79: \E s" Bool"            single data-stack type-prefix f
                     80: \E s" Char"            single data-stack type-prefix c
                     81: \E s" Cell"            single data-stack type-prefix n
                     82: \E s" Cell"            single data-stack type-prefix w
                     83: \E s" UCell"           single data-stack type-prefix u
                     84: \E s" DCell"           double data-stack type-prefix d
                     85: \E s" UDCell"          double data-stack type-prefix ud
                     86: \E s" Float"           single fp-stack   type-prefix r
                     87: \E s" Cell *"          single data-stack type-prefix a_
                     88: \E s" Char *"          single data-stack type-prefix c_
                     89: \E s" Float *"         single data-stack type-prefix f_
                     90: \E s" DFloat *"                single data-stack type-prefix df_
                     91: \E s" SFloat *"                single data-stack type-prefix sf_
                     92: \E s" Xt"              single data-stack type-prefix xt
                     93: \E s" struct F83Name *"        single data-stack type-prefix f83name
1.71      anton      94: \E s" struct Longname *" single data-stack type-prefix longname
1.67      anton      95: \E 
                     96: \E return-stack stack-prefix R:
                     97: \E inst-stream  stack-prefix #
                     98: \E 
                     99: \E set-current
                    100: 
1.1       anton     101: \ 
                    102: \ 
                    103: \ 
                    104: \ In addition the following names can be used:
                    105: \ ip   the instruction pointer
                    106: \ sp   the data stack pointer
                    107: \ rp   the parameter stack pointer
                    108: \ lp   the locals stack pointer
                    109: \ NEXT executes NEXT
                    110: \ cfa  
                    111: \ NEXT1        executes NEXT1
                    112: \ FLAG(x)      makes a Forth flag from a C flag
                    113: \ 
                    114: \ 
                    115: \ 
                    116: \ Percentages in comments are from Koopmans book: average/maximum use
                    117: \ (taken from four, not very representative benchmarks)
                    118: \ 
                    119: \ 
                    120: \ 
                    121: \ To do:
                    122: \ 
                    123: \ throw execute, cfa and NEXT1 out?
                    124: \ macroize *ip, ip++, *ip++ (pipelining)?
                    125: 
                    126: \ these m4 macros would collide with identifiers
                    127: undefine(`index')
                    128: undefine(`shift')
                    129: 
1.47      anton     130: noop   ( -- )          gforth
1.1       anton     131: :
                    132:  ;
                    133: 
1.68      anton     134: lit    ( #w -- w )             gforth
1.1       anton     135: :
                    136:  r> dup @ swap cell+ >r ;
                    137: 
1.47      anton     138: execute        ( xt -- )               core
1.29      crook     139: ""Perform the semantics represented by the execution token, @i{xt}.""
1.1       anton     140: ip=IP;
1.64      anton     141: IF_spTOS(spTOS = sp[0]);
1.1       anton     142: EXEC(xt);
                    143: 
1.47      anton     144: perform        ( a_addr -- )   gforth
1.55      anton     145: ""@code{@@ execute}.""
1.1       anton     146: /* and pfe */
                    147: ip=IP;
1.64      anton     148: IF_spTOS(spTOS = sp[0]);
1.1       anton     149: EXEC(*(Xt *)a_addr);
                    150: :
                    151:  @ execute ;
                    152: 
1.31      jwilke    153:&nbs