Update readme and examples

Author: simon816

README.md

@@ -41,6 +41,11 @@ void main() {
 }
 ```
 
+# Command IR
+
+A new intermediate representation has been developed that the assembly language builds on top of. 
+To find out more see [Command IR](https://github.com/simon816/Command-Block-Assembly/wiki/Command-IR).
+
 # The Assembly Language
 
 It is a simple language with instructions similar to that of x86.
@@ -230,10 +235,10 @@ The assembler is invoked by calling `main.py`.
 
 Command line parameters:
 ```
-usage: main.py [-h] [--world-dir WORLD_DIR] [--as_zip] [--namespace NAMESPACE]
-               [--rem-existing] [--debug] [--stack STACK] [--arg ARG]
-               [--jump JUMP] [--place-location PLACE_LOCATION] [--enable-sync]
-               [--setup-on-load] [--spawn-location SPAWN_LOCATION]
+usage: main.py [-h] [--world-dir WORLD_DIR] [--as-zip] [--namespace NAMESPACE]
+               [--rem-existing] [--debug] [--dump-ir] [--gen-cleanup]
+               [--jump JUMP] --place-location PLACE_LOCATION [--setup-on-load]
+               [--spawn-location SPAWN_LOCATION]
                [--pack-description PACK_DESCRIPTION]
                file
 
@@ -244,17 +249,16 @@ optional arguments:
   -h, --help            show this help message and exit
   --world-dir WORLD_DIR
                         World Directory
-  --as_zip              Write datapack as zip file
+  --as-zip              Write datapack as zip file
   --namespace NAMESPACE
                         Function namespace
   --rem-existing        Remove existing functions in namespace
   --debug               Enable debug output
-  --stack STACK         Stack size
-  --arg ARG             ASM file arguments
+  --dump-ir             Dump Command IR output
+  --gen-cleanup         Generate cleanup function
   --jump JUMP           Output subroutine jump instruction
   --place-location PLACE_LOCATION
                         Location to place command blocks
-  --enable-sync         Enable SYNC opcode
   --setup-on-load       Run setup on minecraft:load
   --spawn-location SPAWN_LOCATION
                         Location to spawn hidden armor stand
@@ -267,21 +271,9 @@ Notes:
 If `--world-dir` is not provided, no functions are written.
 This can be useful in combination with `--debug`.
 
-`--place-location` is where to start laying out command blocks, should they be needed.
-Defaults to `~1,~,~1`
+`--place-location` is where to place a utility command block. It has to be an absolute position e.g. '0,56,0'
 
-`--arg` is used to pass values in to a program that get replaced in the output. They are currently
-only applicable in CMD and TEST instructions.
-e.g.
-```asm
-main: CMD say Hello $arg:name$! This was generated on $arg:date$
-```
-Running `python main.py test.asm --debug --arg "name=Simon" --arg "date=24/10/2017"`
-produces:
-```
-Function sub_main
-  say Hello Simon! This was generated on 24/10/2017
-```
+You may want `--gen-cleanup` which creates a function to remove all scoreboard objectives and the global entity.
 
 ### Running a program
 
@@ -316,45 +308,14 @@ The value is then WORD_SIZE bits in the y axis. i.e. for an 8-bit word, y=0 is t
 `hdd_driver.asm` is a library file, and exports the `read_mem`, `write_mem` subroutines along with
 its constants.
 
-The location where the memory region is defined must be passed in to the assembler:  
-`--arg "mem_loc=0 0 0"`
+The location where the memory region is hardcoded to be `100 60 100`.
 
 #### `mem_test.asm`
 
 A simple test of the hdd_driver library. See description at the top of the file.
 
 # Issues and nuances
 
-## The SYNC instruction (and how it affects CALL and RET)
-
-Command Block Assembly is designed to produce fast and efficient functions,
-avoiding expensive operations wherever possible.  
-As such, some features are optimized unless it is not possible.
-
-By default, a CALL instruction will add a `/function` command to run the subroutine.  
-This means that once the function finishes, execution continues at the next command.  
-This behaviour is the anticipated use of CALL, however the implication is that RET has no effect.
-
-Originally, there was going to be an _implied_ return after a subroutine. i.e. always return to caller if CALL
-is ran.  
-But the RET instruction is required for SYNC to work, so it was added.
-
-As stated in the instruction description, SYNC effectively "pauses" the current execution until one tick later.
-
-The current calling stack (nested `/function` calls) will always return to the caller and continue on the next line.  
-SYNC must nullify the next call so the calling stack returns and the game runs a tick.  
-However, this is not possible with CALL's guarantee to return to caller.
-
-Therefore, CALL must push the address of the next instruction onto the stack, letting RET pop it off later.  
-With that, it is now possible to cause an interrupt between CALL and the subsequent RET.  
-This is how you would expect CALL and RET to function, but doing so is less efficient for the common use-case.
-
-By default, SYNC is disabled. The use of RET prints a warning to stderr saying how it doesn't have any effect.
-If the program is anticipated to use SYNC, you should defensively use RET anyway. Just keep in mind
-how the optimization works.
-
-To use SYNC, enable it with `--enable-sync`.
-
 ## CMP and jumping
 
 Due to there being no concept of a "status" register, jump instructions don't check flags of any sort.  

README_C.md

@@ -16,12 +16,10 @@ Command line parameters:
 ```
 usage: compiler_main.py [-h] [-E] [-S] [--world-dir WORLD_DIR] [--as-zip]
                         [--namespace NAMESPACE] [--rem-existing] [--debug]
-                        [--stack STACK] [--arg ARG]
-                        [--place-location PLACE_LOCATION] [--enable-sync]
-                        [--page-size PAGE_SIZE] [--setup-on-load]
+                        [--dump-ir] [--gen-cleanup] --place-location
+                        PLACE_LOCATION [--page-size PAGE_SIZE]
                         [--spawn-location SPAWN_LOCATION]
                         [--pack-description PACK_DESCRIPTION]
-                        [--extern EXTERN]
                         file
 
 positional arguments:
@@ -38,19 +36,16 @@ optional arguments:
                         Function namespace
   --rem-existing        Remove existing functions in namespace
   --debug               Enable debug output
-  --stack STACK         Stack size
-  --arg ARG             ASM file arguments
+  --dump-ir             Dump Command IR output
+  --gen-cleanup         Generate cleanup function
   --place-location PLACE_LOCATION
                         Location to place command blocks
-  --enable-sync         Enable SYNC opcode
   --page-size PAGE_SIZE
                         Memory page size
-  --setup-on-load       Run setup on minecraft:load
   --spawn-location SPAWN_LOCATION
                         Location to spawn hidden armor stand
   --pack-description PACK_DESCRIPTION
                         Datapack description
-  --extern EXTERN       Specify external symbol
 ```
 
 You will need to generate the standalone parser (from [Lark](https://github.com/lark-parser/lark)) using the `./compiler/rebuild-grammar.sh` script.  

cmd_ir/core.py

@@ -481,7 +481,6 @@ def end(self):
         assert not self.finished
         for block in self.blocks:
             block.end()
-        print("%s is closed: %s" % (self, self.is_closed()))
         self._finished = True
 
     def get_func_table(self):

cmd_ir/optimizers.py

@@ -64,7 +64,7 @@ def visit_pre_insn(self, insn):
         if isinstance(insn, DefineGlobal):
             var = insn._value
             if not var.is_referenced:
-                print("Unreferenced global", var)
+                #print("Unreferenced global", var)
                 return None
         return insn
 
@@ -75,7 +75,7 @@ def visit_global(self, name, var):
 
     def visit_function(self, name, func):
         if not func.extern_visibility and not func.has_usage():
-            print("Dead function", func)
+            #print("Dead function", func)
             self.changed = True
             return None, None
         elim = DeadCodeFuncEliminator()
@@ -98,7 +98,7 @@ def visit_pre_insn(self, insn):
         if isinstance(insn, DefineVariable):
             var = insn._value
             if not var.is_referenced:
-                print("Unreferenced local", var)
+                #print("Unreferenced local", var)
                 return None
         return insn
 
@@ -109,7 +109,7 @@ def visit_local_var(self, name, var):
 
     def visit_block(self, name, block):
         if block.use_count() == 0:
-            print("Dead block", block)
+            #print("Dead block", block)
             return None, None
         self.changed |= DeadCodeBlockEliminator().visit(block)
         return name, block
@@ -169,7 +169,7 @@ def scan(self, insn):
 
     def kill(self, insn):
         if insn in self.kills:
-            print("Kill", insn)
+            #print("Kill", insn)
             return None
         return insn
 
@@ -189,7 +189,7 @@ class BranchInliner(BlockVisitor):
     def visit_insn(self, insn):
         if isinstance(insn, Branch):
             if insn.label.use_count() == 1:
-                print("inline", insn.label, "into", self._block)
+                #print("inline", insn.label, "into", self._block)
                 return insn.label.insns
         return insn
 
@@ -198,7 +198,7 @@ class BranchEliminator(BlockVisitor):
     def visit_insn(self, insn):
         if isinstance(insn, Branch):
             if insn.label.is_empty():
-                print("Empty", insn.label)
+                #print("Empty", insn.label)
                 return None
         if isinstance(insn, (CmpBr, RangeBr)):
             copy = insn.copy()
@@ -208,7 +208,7 @@ def visit_insn(self, insn):
                     changed = True
                     arg.val = None
             if changed:
-                print("Elim br", copy)
+                #print("Elim br", copy)
                 # eliminated whole insn
                 if not copy.if_true and not copy.if_false:
                     return None
@@ -240,22 +240,22 @@ def visit_block(self, name, block):
                 self.changed |= block not in self.data.aliases \
                                or self.data.aliases[block] != insn.label
                 self.data.aliases[block] = insn.label
-                print("Alias", block, "to", insn.label)
+                #print("Alias", block, "to", insn.label)
             # Attempt to inline invoke
             if self.func._varsfinalized and isinstance(insn, Invoke) \
                and not self.func.get_registers():
                  if not insn.func.params and not insn.func.returns:
                     self.changed |= block not in self.data.aliases \
                                    or self.data.aliases[block] != insn.func
                     self.data.aliases[block] = insn.func
-                    print("Alias", block, "to", insn.func)
+                    #print("Alias", block, "to", insn.func)
 
             # Blocks that have one instruction that generates one command
             # are recorded for exec_run substitution
             if insn.single_command():
                 self.changed |= block not in self.data.cmd_aliases
                 self.data.cmd_aliases.add(block)
-                print("Alias", block, "to insn", insn)
+                #print("Alias", block, "to insn", insn)
         return name, block
 
 class AliasRewriter(BlockVisitor):
@@ -273,13 +273,13 @@ def visit_insn(self, insn):
         for arg in new.query(FunctionLike):
             if arg.val in self.data.aliases:
                 changed = True
-                print("Alias re", arg.val, "to", self.data.aliases[arg.val])
+                #print("Alias re", arg.val, "to", self.data.aliases[arg.val])
                 arg.val = self.data.aliases[arg.val]
             # Things like exec_run
             elif arg.val in self.data.cmd_aliases and arg.accepts(CmdFunction):
                 changed = True
                 cmdvar = BlockAsCommand(arg.val)
-                print("Alias cmd", arg.val, "to", cmdvar)
+                #print("Alias cmd", arg.val, "to", cmdvar)
                 arg.val = cmdvar
 
         # Need to update success tracker to new branch
@@ -302,8 +302,8 @@ def visit_insn(self, insn):
         for arg in new.query(Variable):
             if arg.access is READ and arg.val in self.varvals:
                 if arg.accepts(int):
-                    print("Const replace", self.n(arg.val),
-                          "with", self.varvals[arg.val], "in", new)
+                    #print("Const replace", self.n(arg.val),
+                    #      "with", self.varvals[arg.val], "in", new)
                     arg.val = self.varvals[arg.val]
                     changed = True
                 # probably wrong place for this, but can't replace var
@@ -427,8 +427,8 @@ def visit_insn(self, insn):
         # Replace READs
         for arg in new.query(Variable):
             if arg.access is READ and arg.val in self.aliases:
-                print("Alias replace", self.n(arg.val),
-                      self.n(self.aliases[arg.val]))
+                #print("Alias replace", self.n(arg.val),
+                #      self.n(self.aliases[arg.val]))
                 arg.val = self.aliases[arg.val]
                 changed = True
         # Subtracting own alias equivalent to setting to 0

compiler_main.py

@@ -22,10 +22,9 @@
     parser.add_argument('--rem-existing', help="Remove existing functions in namespace",
                         action='store_true')
     parser.add_argument('--debug', action='store_true', help="Enable debug output")
-    parser.add_argument('--dump-ir', action='store_true', help="Dump CMD IR output")
+    parser.add_argument('--dump-ir', action='store_true', help="Dump Command IR output")
     parser.add_argument('--gen-cleanup', action='store_true', help="Generate cleanup function")
-    parser.add_argument('--place-location', default="~1,~,~1",
-                        help="Location to place command blocks")
+    parser.add_argument('--place-location', help="Location to place command blocks", required=True)
     parser.add_argument('--page-size', type=int, default=64, help="Memory page size")
     parser.add_argument('--spawn-location', default='~ ~2 ~',
                         help="Location to spawn hidden armor stand")

examples/hdd_driver.asm

@@ -19,7 +19,7 @@
 ; Set mar to the address to read
 ; mbr will contain the value once read
 read_mem:
-    CMD summon armor_stand $arg:mem_loc$ {Tags:["$tag:_mem_ptr$"], NoGravity:1b, Marker:1b}
+    CMD summon armor_stand 100 60 100 {Tags:["hdd_ptr"], NoGravity:1b, Marker:1b}
     MOV mar, hdd_addr
     MOV #0, mbr
     DIV MEM_SIZE_X, hdd_addr
@@ -31,23 +31,23 @@ read_mem:
     _read_loop:
     CMP hdd_addr, #0
     JE _finish
-    TEST execute at @e[tag=$tag:_mem_ptr$] if block ~ ~ ~ stone
+    TEST execute at @e[tag=hdd_ptr] if block ~ ~ ~ stone
     ADD hdd_mul, mbr
     SUB #1, hdd_addr
     MUL #2, hdd_mul
-    CMD execute as @e[tag=$tag:_mem_ptr$] at @s run tp @s ~ ~1 ~
+    CMD execute as @e[tag=hdd_ptr] at @s run tp @s ~ ~1 ~
     JMP _read_loop
 
     _finish:
-    CMD kill @e[tag=$tag:_mem_ptr$]
+    CMD kill @e[tag=hdd_ptr]
     RET
 
 
 ; Writes a word (WORD_SIZE) to memory
 ; Set mar to the address to write
 ; set mbr to the value that will be written
 write_mem:
-    CMD summon armor_stand $arg:mem_loc$ {Tags:["$tag:_mem_ptr$"], NoGravity:1b, Marker:1b}
+    CMD summon armor_stand 100 60 100 {Tags:["hdd_ptr"], NoGravity:1b, Marker:1b}
     MOV mar, hdd_addr
     DIV MEM_SIZE_X, hdd_addr
     CALL memory_seek
@@ -65,14 +65,14 @@ write_mem:
     CMP _mem_temp, #0
     JE _write_zero
     ; If not zero, write 1. note: this captures -1 and 1
-    CMD execute at @e[tag=$tag:_mem_ptr$] run setblock ~ ~ ~ stone
+    CMD execute at @e[tag=hdd_ptr] run setblock ~ ~ ~ stone
     JMP _continue
-    _write_zero: CMD execute at @e[tag=$tag:_mem_ptr$] run setblock ~ ~ ~ air
-    _continue:   CMD execute as @e[tag=$tag:_mem_ptr$] at @s run tp @s ~ ~1 ~
+    _write_zero: CMD execute at @e[tag=hdd_ptr] run setblock ~ ~ ~ air
+    _continue:   CMD execute as @e[tag=hdd_ptr] at @s run tp @s ~ ~1 ~
     JMP _write_loop
 
     _finish:
-    CMD kill @e[tag=$tag:_mem_ptr$]
+    CMD kill @e[tag=hdd_ptr]
     RET
 
 
@@ -82,7 +82,7 @@ memory_seek:
     CMP hdd_addr, #0
     JE _seek_z
 
-    CMD execute as @e[tag=$tag:_mem_ptr$] at @s run tp @s ~1 ~ ~
+    CMD execute as @e[tag=hdd_ptr] at @s run tp @s ~1 ~ ~
     SUB #1, hdd_addr
     JMP memory_seek
 
@@ -95,7 +95,7 @@ memory_seek:
     JE _end
 
     SUB #1, hdd_addr
-    CMD execute as @e[tag=$tag:_mem_ptr$] at @s run tp @s ~ ~ ~1
+    CMD execute as @e[tag=hdd_ptr] at @s run tp @s ~ ~ ~1
     JMP _seek_z_loop
 
     _end: RET