Description
+ +Lua Assembler/Disassembler is a tool that can be used to generate Lua bytecode and Assembly code.
+Lua bytecode is generated through the assembler provided, while Assembly code is generated by the disassembler,
+which inspects Lua bytecode in order to reproduce it into an Assembly language.
+
+The assembler uses Lpeg in order to implement the parser
+for our Assembly syntax, which is presented on this document.
+
+ +
Requirements
+Lua Assembler/Disassembler is compatible with Lua version 5.2.0 and Lpeg version 0.10.2.
++ +
Install
+
+To run Lua Assembler/Disassembler in your computer, first you need install the
+Lua language and the
+Lpeg library.
+The Lua Assembler/Disassembler may be executed as an application/script and
+can be used as a module in your Lua code too.
+In order to install, please, download the source code, extract it and then
+follow below instructions to have the applications/scripts and modules installed.
+
Installing scripts
++Just copy the following files to a directory in your computer or +to your $PATH (which will depend on the operating system). +
+-
+
luaa.lua
+ luad.lua
+
+Since the applications/scripts use the modules to run assembler and disassembler +functions, please, do not forget to follow below steps in order to get them installed. +
+ +Installing modules
++Just copy the following files to the first directory that is set in package.path. +
+-
+
assembler.lua
+ disassembler.lua
+ ladconf.lua
+
+You can also copy above files to other directory, if that's the case, please, do not +forget to change package.path, in your Lua code, in order to look for the modules +in the directory that you have installed them. +
++ +
Assembler
++The assembler might be used as a stand alone application/script or as a module that +you require in your code. +
+ +Assembler script
+The stand alone application/script is called luaa.lua. + +The following synopsis should be used: + ++lua luaa.lua [options] [filename] ++ +
Available options are listed below and must be separate.
+ +-h
++Just prints a help message listing all available options and a brief explanation about them. +
+ +-o file
++Output to file, instead of the default luaa.out. +Be careful to not overwrite precious files since you might specify the output file as an existent source file. +
+ +Assembler module
++The module is called assembler and something like below line should be used in order to make +its functions available. +
+
+local assembler = require("assembler")
+
+Available functions are listed below.
+ +assembler.parse(contents)
++The function parse gets the contents of an Assembly source code as its only +argument and returns its Abstract Syntax Tree (AST). +
+assembler.traverse(ast)
++The function traverse gets the AST, returned by parse function, and inspects +the AST to find errors. If no errors were found, than all information inside +the AST are combined into a table that will be used to write the correspondent +Lua bytecode. +
+assembler.write(filename, parsed)
++The function write gets two parameters: the first one is the filename were +Lua bytecode should be written, while the second one is the table returned +by traverse function. +
+assembler.print_ast(ast)
++The function print_ast might be used for debug purposes. It receives the AST +as its only parameters and prints it. +
+ ++ +
Disassembler
++The disassembler might be used as a stand alone application/script or as a module that +you require in your code. +
+ +Disassembler script
+The stand alone application/script is called luad.lua. + +The following synopsis should be used: + ++lua luad.lua [options] [filename] ++ +
Available options are listed below and must be separate.
+ +-h
++Just prints a help message listing all available options and a brief explanation about them. +
+-l
++Produce a listing of the compiled bytecode for Lua's virtual machine on luac -l style. +Use -l -l for full listing. +
+-o file
++Output to file, instead of the default luad.asm. +Be careful to not overwrite precious files since you might specify the output file as an existent source file. +
+ +Disassembler module
++The module is called disassembler and something like below line should be used in order to make +its functions available. +
+
+local disassembler = require("disassembler")
+
+Available functions are listed below.
+ +disassembler.parse(bytecode)
+The function parse gets a chunk of Lua bytecode as its only +argument and returns a table containing all information that +are necessary to write its correspondent Assembly code. ++
+disassembler.write(filename, parsed)
+The function write gets two parameters: the first one is the filename were +the Assembly code should be written, while the second one is the table returned +by parse function. ++
+disassembler.print_function(parsed, full)
++The function print_function might be used for printing Lua bytecode in luac -l style. +It has two parameters: the first one is the table returned by parse function and +the second one is a boolean value indication if full listing is expected or not. +
+ ++ +
How To Use
+ +The following command line shows how to use the disassembler in order to generate the assembly code
+for a Lua source file:
+
+$ lua luad.lua -o hello.asm hello.lua ++ +The above command line outputs hello.asm which contains the assembly code for hello.lua. +
+It is important to remember that the
disassembler can be used with a Lua bytecode too, as we shown below:
++$ lua luad.lua luac.out ++ +Notice that in this case we haven't specified the output file, in this way the output will be the default luadd.asm. +
+
The following command line shows how to use the assembler in order to generate Lua bytecode from
+our assembly code:
+
+$ lua luaa.lua -o hello.out hello.asm ++ +The above command line outputs hello.out which contains Lua bytecode for hello.asm and can be executed using lua. +
+It is important to remember that if you do not specify the output file, then Lua bytecode will be generated as luaa.out by default. + +
+ +
Examples
+ +In this section we show some examples of our assembly language. The complete syntax can be checked +at Assembly Syntax as well as opcodes can be checked at Instructions. + +Here we show the assembly code that were generated, on above section, for hello.lua which is a simple +hello world program. + ++function main(0): + 1 [1] GETTABUP $0, _ENV, "print" + 2 [1] LOADK $1, "hello world!" + 3 [1] CALL $0, 2, 1 + 4 [1] RETURN $0, 1 ++ +Once we use the
assembler to output the Lua bytecode we can execute it using lua, as follows:
+
++$ lua hello.out +hello world! +$ ++ +Now we define a recursive factorial in our Assembly language. Notice that line number and +source line number are not needed when we are writting the Assembly code. However, they are +generated when the disassembler process is performed. + +
+function main(0): + CLOSURE $0, fat + SETTABUP _ENV, fat, $0 + GETTABUP $0, _ENV, print + GETTABUP $1, _ENV, fat + LOADK $2, 5 + CALL $1, 2, 0 + CALL $0, 0, 1 + RETURN $0, 1 + +function fat(1): + EQ 0, $0, 0 + JMP 0, label1 ; jump to label1 + LOADK $1, 1 + RETURN $1, 2 +label1: GETTABUP $1, _ENV, fat ; create label1 + SUB $2, $0, 1 + CALL $1, 2, 2 + MUL $1, $0, $1 + RETURN $1, 2 + RETURN $0, 1 ++ +Notice that we have used a label in fat function since it is easier to check where to jump +when we are writing manual assembly code. +Also notice that a comment starts with a semicolon (;) and finishes at the end of the line. +A function main is necessary for all Assembly codes and the number of +parameters for the function that is being defined should be specified between +parenthesis. + +
+ +
Assembly Syntax
+ +Here is the complete syntax of Assembly inlpeg re module.
+
+
+ prog <- s function* !.
+ function <- header codelist
+ header <- "function" s name s "(" s n s ")" s ":" s
+ codelist <- code+
+ code <- autocode / manualcode
+ autocode <- n s ln s op s param s ("," s param s)*
+ manualcode <- (label s)? op s param s ("," s param s)*
+ n <- %d+
+ label <- name ":"
+ name <- !reserved {[a-zA-Z_][a-zA-Z0-9_]*}
+ ln <- "[" %d+ "]"
+ op <- !reserved %a+
+ param <- register / number / string
+ register <- "$" n
+ number <- hex / float / int
+ string <- name / shortstr
+ shortstr <- '"' ('\\' / '\"' / !'"' .)* '"' / "'" ("\\" / "\'" / !"'" .)* "'"
+ hex <- "-"? "0" [xX] %x+
+ float <- "-"? ( (%d+ "." %d* / "." %d+) e? / %d+ e )
+ e <- [eE] [+-]? n
+ int <- "-"? n
+ s <- (space / comment)*
+ space <- %s+
+ comment <- ";" (!%nl .)*
+ reserved <- "function"
+
++ +
Instructions
+ ++We have four main types of instructions, they are so called iABC, iABx , iAsBx +and iAx. The instructions should be used as follows: +
+ +| Instruction type | +Pattern | +
| iABC | +OPCODE A, B, C | +
| iABx | +OPCODE A, Bx | +
| iAsBx | +OPCODE A, sBx | +
| iAx | +OPCODE Ax | +
+Some iABC instructions do not use argument B or C and below we specify when that is the case. +Nonetheless, most of the iABC instructions follow the pattern described in above table. +
+ ++It is also important to keep in mind that parameters should comply with the Assembly Syntax. +Here a some examples: +
+ +| Parameter type | +Example | +
| Register | +$0, $1, $2, ... | +
| Number | +0, 1, 2, ... / -1, -2, ... / 0.1, 0.2, ..., 1.0, 1.1, ... / -0.1, -0.2, ..., -1.0, -1,1, ... | +
| Name | +F_0_1, blah, foo, ... | +
| String | +"oi, tudo bem?", "hello world", "%s, string", ... | +
+We will use a instruction notation as follows to show how to use each opcode. +
+ +| Notation | +Meaning | +
| R(A), R(B), R(C) | +Register specified in field A, B or C. | +
| PC | +Program Counter. | +
| Kst(k) | +A constant k that will be translated to a number. | +
| Upvalue(name) | +An upvalue name that will be translated to a number. | +
| RK(B), RK(C) | +A field that could be a register or a constant. | +
| sBx | +Signal displacement for all kinds of jumps. It can be a number or a label. | +
| KPROTO(name) | +A function name that will be used to create its closure. | +
+Below we show each opcode that is available in our assembly language as well as their respective arguments. +
+ +MOVE R(A), R(B)
+R(A) := R(B) ++Copies the value of register R(B) into register R(A). +
+LOADK R(A), Kst(Bx)
+R(A) := Kst(Bx) ++Loads constant Kst(Bx) into register R(A). Constants can be numbers or strings. +
+LOADKX R(A)
+R(A) := Kst(extra arg) ++Loads extra arg into register R(A). +The next instruction is always EXTRAARG. +
+LOADBOOL R(A), B, C
+R(A) := (Bool)B; if (C) pc++ ++Loads a boolean value B (1 for TRUE or 0 for FALSE should be used as B) into register R(A). +If C is not zero then next instruction is skipped. +
+LOADNIL R(A), B
+R(A), R(A+1), ..., R(A+B) := nil ++Sets to nil a range of registers from register R(A) up to B. +
+GETUPVAL R(A), UpValue(B)
+R(A) := UpValue[B] ++Copies the value in UpValue[B] into register R(A). +
+GETTABUP R(A), UpValue(B), RK(C)
+R(A) := UpValue[B][RK(C)] ++Copies the value of field RK(C), from table UpValue[B], into register R(A). +Note that if you are getting globals, then UpValue(B) should be _ENV. +
+GETTABLE R(A), R(B), RK(C)
+R(A) := R(B)[RK(C)] ++Copies the value from a table element into register R(A). +The table is referenced by register R(B), while the index to the table is given by +RK(C), which may be register R(C) or a constant Kst(C). +
+SETTABUP UpValue(A), RK(B), RK(C)
+UpValue[A][RK(B)] := RK(C) ++Copies the value of RK(C) to the field RK(B) of table UpValue[A]. +Note that if you are setting globals, then UpValue(A) should be _ENV. +
+SETUPVAL R(A), UpValue(B)
+UpValue[B] := R(A) ++Copies the value from register R(A) into UpValue[B]. +
+SETTABLE R(A), RK(B), RK(C)
+R(A)[RK(B)] := RK(C) ++Copies the value from register R(C) or constant Kst(C) into a table element. +The table is referenced by register R(A), while the index to the table is given by +RK(B), which may be register R(B) or a constant Kst(B). +
+NEWTABLE R(A), B, C
+R(A) := {} (size = B,C) ++Creates a new empty table at register R(A). +Argument B is the size of the array part, while C is the size of the hash part. +
+SELF R(A), R(B), RK(C)
+R(A+1) := R(B); R(A) := R(B)[RK(C)] ++It is used for object-oriented programming using tables. +Retrieves a function reference from a table element and places it in register R(A), +then a reference to the table itself is placed in the next register R(A+1). +R(B) is the register holding the reference to the table with the method, +while the method function is found using the table index RK(C), that can be +a register R(C) or a constant Kst(C). +
+ADD R(A), RK(B), RK(C)
+R(A) := RK(B) + RK(C) ++Adds RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+SUB R(A), RK(B), RK(C)
+R(A) := RK(B) - RK(C) ++Subtracts RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+MUL R(A), RK(B), RK(C)
+R(A) := RK(B) * RK(C) ++Multiplies RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+DIV R(A), RK(B), RK(C)
+R(A) := RK(B) / RK(C) ++Divides RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+MOD R(A), RK(B), RK(C)
+R(A) := RK(B) % RK(C) ++Performs modulus between RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+POW R(A), RK(B), RK(C)
+R(A) := RK(B) ^ RK(C) ++Performs exponentiation between RK(B) and RK(C) and holds the result into register R(A). +Both RK(B) and RK(C) may be either registers or constants. +
+UNM R(A), R(B)
+R(A) := -R(B) ++Performs unary minus where register R(B) is negated and the value is placed in register R(A). +
+NOT R(A), R(B)
+R(A) := not R(B) ++Applies a boolean not to the value in register R(B) and holds the result in register R(A). +
+LEN R(A), R(B)
+R(A) := length of R(B) ++Returns the length of object in register R(B) and holds the result in register R(A). +
+CONCAT R(A), R(B), R(C)
+R(A) := R(B).. ... ..R(C) ++Performs the concatenation among two or more strings. The start register is R(B) and the +final register is R(C), meaning that R(C) should always be greater then R(B). +The result is stored in register R(A). +
+JMP A, sBx
+pc+=sBx; if (A) close all upvalues >= R(A) + 1 ++Performs a jump to sBx, which should be an instruction number or a label that should jump to. +If A is true then all upvalues up to R(A) + 1 are closed. +
+EQ A, RK(B), RK(C)
+if ((RK(B) == RK(C)) ~= A) then pc++ ++Performs a equality test between RK(B) and RK(C), wich may be registers or constants. +If the boolean is not A then next instruction is skipped. +
+LT A, RK(B), RK(C)
+if ((RK(B) < RK(C)) ~= A) then pc++ ++Performs a less than test between RK(B) and RK(C), wich may be registers or constants. +If the boolean is not A then next instruction is skipped. +
+LE A, RK(B), RK(C)
+if ((RK(B) <= RK(C)) ~= A) then pc++ ++Performs a less than or equal to test between RK(B) and RK(C), wich may be registers or constants. +If the boolean is not A then next instruction is skipped. +
+TEST R(A), C
+if not (R(A) <=> C) then pc++ ++Can be used to implement and/or logical operators, or for testing +a single register in a conditional statement. +TEST should be used when an assignment operation is not needed and works same way as TESTSET. +For more details, please, look at TESTSET. +
+TESTSET R(A), R(B), C
+if (R(B) <=> C) then R(A) := R(B) else pc++ ++Also can be used to implement and/or logical operators, or for testing +a single register in a conditional statement. +Register R(B) is coerced into a boolean and compared to the boolean field C. +If R(B) matches C then next instruction is skipped, otherwise R(B) is assigned to R(A). +
+CALL R(A), B, C
+R(A), ... ,R(A+C-2) := R(A)(R(A+1), ... ,R(A+B-1)) +
+Performs a function call. R(A) holds the reference to the function object to be called.
+Parameters to the function should be placed in the registers following R(A).
+
+If B is 1 the function has no parameters. If B is 2 or more there are B-1 parameters.
+If B is 0 the function parameters range from R(A+1) to the top of the stack.
+
+Results returned by the function call are placed in a range of registers starting from R(A).
+If C is 1 no return results. If C is 2 or more there will be C-1 results saved.
+If C is 0 then multiple return results are saved.
+
TAILCALL R(A), B, C
+return R(A)(R(A+1), ... ,R(A+B-1)) ++Performs a tail call which happens when a return statement has a single function call as the expression. +Exactly like CALL, register R(A) is the reference to the function object to be called, +while B encodes the number of paramenters. However, even tough C is not used by TAILCALL, 0 should be +used to denote multiple return results. +
+RETURN R(A), B
+return R(A), ... ,R(A+B-2) +
+Returns to the calling function with options return values.
+
+If B is 1 there are no return values. If B is 2 or more, there are B-1 return values.
+If B is 0 the set of values from R(A) to the top of the stack is returned.
+
FORLOOP R(A) sBx
+R(A)+=R(A+2) ; if R(A) <?= R(A+1) then pc+=sBx; R(A+3)=R(A) ++Should be used to perform an iteration of a numeric for loop. +A numeric for loop requires 4 registers on the stack where R(A) hold the initial value, +R(A+1) is the limit, R(A+2) is the stepping value and R(A+3) is the actual loop variable +that is local to the for block. +The argument sBx should be an instruction number or a label that should jump unconditionally to. +
+FORPREP R(A), sBx
+R(A)-=R(A+2); pc+=sBx ++Should be used to initialize a numeric for loop. +The argument sBx should be an instruction number or a label that should jump back to the loop body. +
+TFORCALL R(A), C
+R(A+3), ... ,R(A+2+C) := R(A)(R(A+1), R(A+2)) ++Should be used to initialize a generic for loop, where +R(A) is the iterator function, R(A+1) is the state and R(A+2) is the enumeration index. +The loop variables are specified at locations R(A+3) and their count is defined by operand C, +which should be at least 1. +
+TFORLOOP R(A), sBx
+if R(A+1) ~= nil then { R(A)=R(A+1); pc += sBx } ++Should be used to perform an iteration of a generic for loop. +If register R(A+1) is not nil then it is stored in R(A) and jump back to sBx. +The argument sBx should be an instruction number or a label that should jump to. +
+SETLIST R(A), B, C
+R(A)[(C-1)*FPF+i] := R(A+i), 1 <= i <= B ++Sets the values for a range of arrays elements in a table referenced by R(A), +argument B is the number of elements to set and argument C is the number of blocks +to be initialized. +If B is zero then B is the top. If C is zero then next instruction should be +EXTRAARG(real C). +
+CLOSURE R(A), KPROTO(Bx)
+R(A) := closure(KPROTO[Bx]) ++Should be used to create an instance of a closure of a function where KPROTO[Bx] is the +function name and R(A) is the register that assigns the reference to the instantiated +function object. +
+VARARG R(A), B
+R(A), R(A+1), ..., R(A+B-2) = vararg ++Copies B-2 parameters into a number of registers starting from R(A). +If B is 0, VARARG copies as many values as it can based on the number of parameters passed. +If a fixed number of values is required, B is a value greater than 1. +If any number of values is required then B is 0. +
+EXTRAARG Ax
++Sets an extra larger argument for previous opcode. +If previous opcode is LOADKX then Ax might be any constant, but +if previous opcode is SETLIST then Ax must be an integer. +
+ ++ +
Notes
+
+The current version of Lua Assembler/Disassembler is 0.2.
+
+ +
Licence
++Copyright © 2012 Andre Murbach Maidl. +
++Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to +deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +
++The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +
++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +
+ +