adoc/p_create.adoc

   1 // compile.asm: WORD p_create,'CREATE',fasm
   2
   3 anchor:p_create[]
   4
   5 === Word: CREATE
   6
   7
   8 ....
   9 Data stack: ( char* n -- tfa )
  10 ....
  11
  12 "CREATE" is a function word that allocates a "word header" with the
  13 indicated [n:char*] print name, and returns the "TFA" (Token Field
  14 Address) of the word. The header memory layout is as follows:
  15
  16 ====
  17 .rrqforth word structure
  18 [caption='Layout {counter:layout}: ']
  19 ----
  20 struct WORD
  21 TFA  8 link ; tfa of previous word
  22 pCFA 8 cfap ; CFA = Code Field Address of this word
  23      8 flags ;
  24 PFA  8 length ; length of pname representation
  25      ? pname ; the pname bytes
  26      1 nul ; a forced nul byte following the pname
  27 pTFA 8 tfap ; TFA = Token Field Address of this word
  28 OFF  8 doff ; entry offset for FORTH level execution
  29 CFA  8 doer ; word execution semantics
  30 DFA  0 content ; DFA = Data Field Address
  31 end_struct
  32 ----
  33 ====
  34
  35 A "word" is generally understod as a marker in memory for some content
  36 as held in the memory space following the DFA (Data Field Address).
  37
  38 The words CFA (Code Field Address) is the most important field for
  39 RRQFORTH execution, as holding a jump address to the assembly code
  40 that implements the particular execution semantics for the word.
  41 "CREATE" will assign this as "dovariable", which makes the word push
  42 its DFA when executed. This is changed to "doforth" for RRQFORTH
  43 function words initiated by ":" (aka "COLON") or changed to "dovalue"
  44 for RRQFORTH constants created by "CONSTANT".
  45
  46 ====
  47 .Definition concept for CREATE
  48 ****
  49 HERE @ R> ( save tfa on RS )
  50   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
  51   DUP 49 + R@ + ,             ( pCFA )
  52   0 ,                         ( flags )
  53   DUP , ( length )
  54   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
  55   R@ ,                        ( pTFA )
  56   0 ,                         ( OFF )
  57   doVARIABLE                  ( CFA, default semantics )
  58 ****
  59 ====
  60
  61 ====
  62 .a possible definition of CONSTANT
  63 [caption='Usage example {counter:example}: ']
  64 ----
  65 : CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
  66 ----
  67 ====
  68
  69 See also <<p_put,!>>, <<p_plus,+>>, <<p_comma>>, <<p_get,@>>,
  70 <<p_Ccomma>>, <<p_current_word,CURRENT-WORD>>, <<p_dup,DUP>>,
  71 <<p_here,HERE>>, <<p_herememcpy,HERE>>, <<p_Rget,R@>>, <<p_rot,ROT>>,
  72 and <<p_dovariable,doVARIABLE>>,
  73 as well as <<p_execute,EXECUTE>>
  74 about the range of "doer" assignments and their meanings.