basis/compiler/cfg/stacks/clearing/clearing-docs.factor

   1 USING: compiler.cfg compiler.cfg.instructions help.markup
   2 help.syntax kernel sequences strings ;
   3 IN: compiler.cfg.stacks.clearing
   4
   5 ARTICLE: "compiler.cfg.stacks.clearing" "Uninitialized stack location clearing"
   6 "A compiler pass that inserts " { $link ##clear } " instructions front of instructions which requires the whole stack to be initialized. Consider the following sequence of instructions:"
   7 { $code
   8   "##inc D: 2"
   9   "..."
  10   "##allot"
  11   "##replace ... D: 0"
  12   "##replace ... D: 1"
  13 }
  14 "The GC check runs before stack locations 0 and 1 have been initialized, so they need to be cleared as they can contain garbage data which could crash Factor if it tries to trace them. This is achieved by computing uninitialized locations with a dataflow analysis (see " { $vocab-link "compiler.cfg.stacks.padding" } ") and then inserting clears so that the instruction sequence becomes:"
  15 { $code
  16   "##inc D: 2"
  17   "..."
  18   "##clear D: 0"
  19   "##clear D: 1"
  20   "##allot"
  21   "##replace ... D: 0"
  22   "##replace ... D: 1"
  23 }
  24 "Similar dangerous stack 'holes' needs to be padded in the same way to guard unsafe " { $link ##peek } " instructions. E.g:"
  25 { $code
  26   "##inc D: 2"
  27   "##peek RCX D: 2"
  28 }
  29 "Here the ##peek can cause a stack underflow and then there will be two uninitialized locations on the captured data stack that can't be traced. As in the previous example, ##clears are inserted on locations D: 0 and D: 1." ;
  30
  31 HELP: dangerous-insn?
  32 { $values { "state" "a stack state" } { "insn" insn } { "?" boolean } }
  33 { $description "Checks if the instruction is dangerous, meaning that the holes in the stack must be filled before it is executed." }
  34 { $examples
  35   { $example
  36     "USING: compiler.cfg.instructions compiler.cfg.registers compiler.cfg.stacks.clearing prettyprint ;"
  37     "{ { 0 { } } { 0 { } } } T{ ##peek { loc D: 0 } } dangerous-insn? ."
  38     "t"
  39   }
  40   { $example
  41     "USING: compiler.cfg.instructions compiler.cfg.registers compiler.cfg.stacks.clearing prettyprint ;"
  42     "{ { 0 { } } { 2 { } } } T{ ##peek { loc R: 0 } } dangerous-insn? ."
  43     "f"
  44   }
  45   { $example
  46     "USING: compiler.cfg.instructions compiler.cfg.registers compiler.cfg.stacks.clearing prettyprint ;"
  47     "{ { 0 { } } { 3 { } } } T{ ##call-gc } dangerous-insn?"
  48     "t"
  49   }
  50 } ;
  51
  52
  53 ABOUT: "compiler.cfg.stacks.clearing"