Register | Login
Home > Documentation

Ziron Documentation

Last update: 31.01.2015 2055h UTC+2

Contents

Prelude
Commandline Options
Identifiers and Symbols
Constants
Data Types
Structures / Blocks
Arrays
Expressions
Conditional blocks/statements
Functions and Procedures
Macros and eMacros
Intrinsic Macros and Directives
Ziron Linker and File Formats
Plugin API
Assembly Reference

Prelude

Ziron is a language that aims to allow developers to use the power of assembly while maintaining the easy to read syntax of higher level languages. The syntax resembles plain Assembly, Pascal, C and PHP along with many unique elements.

Commandline Options

Command line options are passed to the Ziron executable as arguments. e.g. Ziron.exe inputfile.zir -argname value.
Name Usage Note
out -out myfile.exe Forces the output file to a specific filename.
i -i "c:/myincludes" Sets an extra include directory to search.
nopause -nopause Assembler will not pause regardless of output.
writelog -writelog A log file will be written to disk.
asmdebug -asmdebug Output info regarding the assembly of instructions.
program -program KOLIBRI32 Sets the program type, overriding the source type.

Identifiers and Symbols

Identifiers are any upper or lowercase word that contains only characters A-Z, 0-9 and _, but can not start with a number. Identifiers are used when declaring variables, constants, functions, macros and other user keywords.

Some example identifiers:

myIdent
my_Ident
my_Ident23
m_y_i_d_e_n_t_1
i


Example of invalid identifiers:

1ident          // numbers are invalid for first character.
3_ident         // again a number as first character.
my ident        // no spaces are permitted in identifiers.
my-ident        // hyphens are other special characters are invalid.


Symbol / Operator Usage Note
// // my comment Single line comment.
/* /* my comment */ Multi-line comment open.
*/ /* my comment */ Multi-line comment close.
= eax = edx; Assignment operator.
! eax = !edx; Not equal assignment.
+ $var1 = $var2 + $var3; Addition operator.
- $var1 = $var2 - $var3; Subtraction operator.
* $var1 = $var2 * $var3; Multiplcation operator.
/ $var1 = $var2 / $var3; Division operator.
& const CONST_1 = CONST_2 & CONST_2 Bitwise and.
| const CONST_1 = CONST_2 | CONST_2 Bitwise inclusive or.
^ const CONST_1 = CONST_2 ^ CONST_2 Bitwise exclusive or.
<< eax << 5; Bit shift left.
>> eax >> 5 Bit shift right.
++ eax++; Increment
-- eax--; Decrement
+= eax += 5; Addition
-= eax -= 5; Subtraction
*= eax *= 5; Multiplication
|= eax |= edx; Bitwise inclusive or.
^= eax ^= edx; Bitwise exclusive or.
&= eax &= edx; Bitwise and.
== if (eax == edx) { Is equal
<> if (eax <> edx) { Is not equal
< if (eax < edx) { Is lower than
> if (eax > edx) { Is higher than
<= if (eax <= edx) { Is lower or equal
>= if (eax >= edx) { Is higher or equal
!= if (eax != edx) { Is not equal
@ eax = @myVariable; Address of
[] myStr = [char*]eax; [edx+ecx] = 5; Typecasting and memory operands.
$ $if $var1 = $var2: Directives and Macro variable prefix.
# #include 'file.zir'; Directives and inbuilt methods.

Constants

Declaring constants

Constants can be declared almost anywhere in a program before the usage. Constants declared inside of a method are local constants and remain in the scope of the method.

Declaring a constant is as follows: const name = value;.

A few examples of declaring constants:
const name = 'Ziron Assembler';
const version = 2.0;
const value = 0x64;


Reserved constants

Ziron has several constants that are reserved for use with the assembler and linker for different image types.
Name Image type Notes
_FILE_PATH_ KOLIBRI32 and MENUET01 Accesses the image path.
_PARAM_STR_ KOLIBRI32 and MENUET01 Accesses the parameters.

Note that these are declared individually for cross platform support inside of the includes of the target platform.

Data Types

Inbuilt types of variables

Name Size (bytes) Range
byte 1 0 .. 255
char 1 0 .. 255
word 2 0 .. 65535
wchar 2 0 .. 65535
widechar 2 0 .. 65535
dword 4 0 .. 4294967295
boolean 4 0 .. 4294967295
qword 8 0 .. 18446744073709551615
pointer 2, 4 or 8 0 .. [platform dependant]
sysword 2, 4 or 8 0 .. [platform dependant]
sbyte 1 -128 .. 127
int8 1 -128 .. 127
int16 2 -32768 .. 32767
short 2 -32768 .. 32767
int32 4 -2147483648 .. 2147483647
int64 8 -9223372036854775808 .. 9223372036854775807
sysint 2, 4 or 8 0 .. [platform dependant]
single 4 1.5E-45 .. 3.4E38
real4 4 1.5E-45 .. 3.4E38
double 8 5.0E-324 .. 1.7E308
real8 8 5.0E-324 .. 1.7E308
extended 10 1.9E-4932 .. 1.1E4932
real10 10 1.9E-4932 .. 1.1E4932

Declaring variables

Variables can be declared almost anywhere in a program before the usage. Variables declared inside of a method are local variables and are destroyed on returning from the method where-as global variables remain.

Declaring a variable is as follows: type name;.

A few examples of declaring variables:
word day, month, year;
single weight;
boolean isActive;

Global variables can be initialized with constants.
word year = 2015;

Structures / Blocks

Syntax

Blocks are a way of storing multiple fields of data into 1 easy to access variable name. The syntax is simple:

block <name> {
    <type> <name>
    <type> <name>
    ...
}


An example of a block:

block HUMAN {
    char foreName[32];
    char surName[32];
    byte age;
    byte iq;
}


Union

A union allows for several types and names to share the same space inside a block.

block HUMAN {
    char foreName[32];
    char surName[32];
    byte iq;
    union {
        byte age;
        DATETIME dob;
    }
}


Initialization

Coming soon...

Arrays

Arrays are variables that can hold multiple types of data using an index.

dword my_array[5];

The above example will create 5 dword variables accessed using a 0-based index. For example, accessing DWORD 2 will use index 1, 4 will be 3 and so fourth.

Arrays can also be initialized in several ways.

dword my_arr1[] = [4,8,16,32,64]; // 5 dwords
dword my_arr2[2] = [1,2]; // 2 dwords
byte my_arr3[] = 'Hello World!\x0'; // 13 bytes

dword my_arr4[12] = [1,2]; // 12 dwords, 10 of which are null filled.


An example of accessing arrays:

dword my_arr[12] = [1,2,3,4,5,6];
eax = my_arr[0]; // eax = 1
eax = my_arr[eax]; // eax = 2

my_arr[eax] = 10; // my_arr[2] = 10;

// The final result, the array looks like [1,2,10,4,5,6,0,0,0,0,0,0]

Expressions

In Ziron, expressions are used in several cases such as macro variables, consts and conditional statements.

Expressions can use different symbols that represent an action or condition. Please see identifiers.

eax += edx; // add edx to eax

if (eax < 15) { // compare if eax is below 15

while (var <> 0) { // repeat while var does not equal 0/null

Conditional blocks/statements

Coming soon!

Functions and Procedures

Coming soon!

Macros and eMacros

Macros are used as a way of shorting your programming time and simplifying repeatative tasks.

Syntax

inline <procedure|function> <name>($<param1>, $<param2>, ...) {
    // code
}


An example of a macro:

inline procedure xor_some_regs() {
    eax ^= eax;
    ecx ^= ecx;
    edx ^= edx;
}


eMacros

eMacros are similar to the standard inline macros, however they work using events and contain inner block code.

emacro <name>($<param1>, $<param2>, ...) {
    // code
}


When calling the eMacro, code is placed inside of { and }. eMacros contain a reserved macro variable $STATE which contains the current event of the macro, thse can be MACRO_START and MACRO_END. eMacros can also not return values.

emacro doSomething() {
    $if $STATE == MACRO_START:
       // code
    $elseif $STATE == MACRO_START:
       // code
    $end;
}



Note that params always begin with $ and if params are replaced with a single semicolin (;), this represents uncounted arguments.

Uncounted arguments are accessed via the virtual macro array $arg[], you can get the total count using $argc.

Ziron Linker and File Formats

Ziron comes with it's own linker plugin which supports a variety of formats and extended in newer releases. Ziron can have numerous other formats added via plugins. This documentation only currently covered the included linker.dll formats.

PE32_GUI

PE32_GUI creates a Windows x32 compatible executable (.exe) which is designed to run as a graphical user interface.

PE32_CUI

PE32_CUI creates a Windows x32 compatible executable (.exe) which is designed to run as a console user interface.

PE32_DLL

PE32_DLL creates a Windows x32 compatible dynamic link library (.dll).

PE32P_CUI

PE32P_CUI creates a Windows x64 compatible executable (.exe) which is designed to run as a graphical user interface.

PE32P_GUI

PE32P_GUI creates a Windows x64 compatible executable (.exe) which is designed to run as a console user interface.

MSCOFF

MSCOFF creates a Microsoft compatible COFF object file (.obj) which can be linked with MSCOFF compatible linkers.

RAW_IMAGE

RAW_IMAGE creates a plain raw file that can be used to create numerous file formats (.raw)

INTEL_FLOPPY

INTEL_FLOPPY creates a plain bootable raw file with a 1.4MB filesize which is compatible with intel based systems that can be used to create bootloaders among other things (.img)

KOLIBRI32

KOLIBRI32 creates a Kolibri OS x32 compatible executable (.kex).

MENUET01

MENUET01 creates a Menuet OS x32 compatible executable (...).

Intrinsic Macros and Directives

The following methods and macros are built into the assembler and do not use an external library.

Methods marked with a * mean you may interchange $ and #. The # symbol is used usually for global scope, while $ represents a local scope.

Methods / Commands

Name Param count Parameters Sample usage
ord 1 input 1 al = ord('a');
sizeof 1 input 1 eax = sizeof 'This string';
casttype 1 input 1 $ct = casttype($arg[0]);
tokentype 1 input 1 $tt = tokentype($arg[0]);
tokentext 1 input 1 $text = tokentext(eax);
isptrtype 1 input 1 $if isptrtype($arg[0]) == true:
issignedtype 1 input 1 $if issignedtype($arg[0]) == true:
$strcat 2 input 1, input 2 $mystr = $strcat($str1, 'another string');
$substr 3 input, offset, length $mystr = $substr('Hello World', 7, 5);
$strindex 2 input, find $myofs = $strindex('Hello World', 'World');
$echo * 1 input $echo 'Hello World';
$raise * 1 input $raise 'An error occured!';
$depreciated * 1 input $depreciated 'This macro is depreciated!';
$eval * 1 input $eval('mov eax, 5');
$mpush * 1 input $mpush 'Hello World';
$mcall * 2 input, params $mcall myMacro, 5;
$return * 1 value $return eax;
#align * 0 #align;
#include * 1 input #include 'myfile.zir';
#tryinclude * 1 input #tryinclude 'myfile.zir';
#resource * 1 input #resource 'compiledresource.res';
#define * 2 name, value #define MY_REGISTER eax;
#if * 1, 2 [expression] #if $bool:
   // conditional code
#end;

#if $bool == true:
   // conditional code
#end;

#if $value == 1:
   // conditional code
#elseif $value > 4:
   // conditional code
#else
   // conditional code
#end;
#ifdef * 1, 2 [expression] #ifdef MY_REGISTER:
   // conditional code
#end;

#ifdef MY_REGISTER == eax:
   // conditional code
#end;
#ifndef * 1, 2 [expression] #ifndef MY_REGISTER:
   // conditional code
#end;

#ifndef MY_REGISTER == edx:
   // conditional code
#end;
$repeat * 1 count $repeat 100:
   // repeating output
$end;
#set * 2 directive, value #set bits 32;

Directives

Directive Possible values Info
frame on, off Enable or disable procedure stack frame.
defaultcc stdcall, cdecl, msx64 Set the default calling convention.
m2m_reg true, false Enable or disable memory move EAX preservation.
stack_size [value] Set the stack size.
bits 16, 32, 64 Set the bits mode of the instruction assembler.
relocations true, false Enable or disable relocations.
optimise on, off Enable or disable optimisations.
imm_roll yes, no Immediate values should roll around data type. e.g. byte 257 = 1.
awd true, false Always write/activate variables.

Plugin API

Definitions and Structs

TRIGGER_EVENT

enum TRIGGER_EVENT: DWord {
   TRIGGER_START = 0,
   TRIGGER_COMPLETE = 1
}

TRIGGER_START Passed when the trigger is about to begin.
TRIGGER_COMPLETE Passed when the trigger has completed.


Methods exportable by Plugins

onEntry

procedure stdcall onEntry(pointer funcTable): char*;

This function must be exported for it to be a valid Ziron plugin.

funcTable Pointer to the plugin API method table.

Plugin must return an address to a null terminated string which contains the name of the plugin.

onExit

procedure stdcall onExit();

This function can be exported if any deinitialization code is required.

onFileEntry

procedure stdcall onFileEntry(DWord handle; char* pCode; DWord len): boolean;

Export this program to receive events for each file/vfile that is included.

handle The internal handle of the file.
pCode Pointer to the code/file buffer.
len Length of the code/file buffer.

The return is currently unused.


Callback definitions

[onBuildEvent] [related method: ziron_reg_builder]

function stdcall onBuildEvent(TRIGGER_EVENT evt; DWord id): boolean;

Called on file build event.

evt Returns the current event. TRIG_START = 0, TRIG_COMPLETE = 1.
id The unique id for this file type.

Return result is currently unused.

[onKeywordEvent] [related method: ziron_register_keyword]

function stdcall onKeywordEvent(): boolean;

Called on keyword triggered.

Return true if keyword was processed or return false if the assembler should try to process the keyword instead.


Methods callable by Plugins using the function table.

Please note that the names used are using the default method names from the framework include. You can manually call methods from the address or assign them to custom method names as desired.

ziron_log_messageA [table offset: 0]

procedure stdcall ziron_log_messageA(char* msg; boolean fatal);

Output a message to the assembler console.

msg Pointer to a null terminated ansi string containing your message.
fatal True to prevent further assembling.

ziron_log_messageW [table offset: 4]

procedure stdcall ziron_log_messageW(wchar* msg; boolean fatal);

Output a message to the assembler console.

msg Pointer to a null terminated wide string containing your message.
fatal True to prevent further assembling.

ziron_reg_builder [table offset: 8]

function stdcall ziron_reg_builder(char* name; pointer cb): int32;

Register a file builder callback.

name Pointer to a null terminated ansi string containing the file format name. e.g. KOLIBRI32
cb Pointer to the callback function (see events)

This function returns a unique ID for this builder.

ziron_file_commit [table offset: 12]

procedure stdcall ziron_file_commit();

Commits file buffer to disk.

ziron_file_write [table offset: 16]

function stdcall ziron_file_write(pointer bytes; DWord len): DWord;

Write bytes to end of file buffer.

bytes Pointer to a buffer.
len Length of buffer to write.

Returns the file position where the bytes were written.

ziron_file_len [table offset: 20]

function stdcall ziron_file_len(): DWord;

Get the current file buffer size.

Returns the size of the file buffer in bytes.

ziron_file_rewrite [table offset: 24]

function stdcall ziron_file_rewrite(DWord pos; pointer bytes; DWord len): DWord;

Rewrite bytes in file buffer.

pos Position in buffer where the replacement will occur.
bytes Pointer to a buffer.
len Length of buffer to write.

Returns the file position where the bytes were written.

ziron_code_get [table offset: 28]

function stdcall ziron_code_get(DWord i; DWord* len): pointer;

Get the code from function.

i ID of the method.
len Pointer to a DWord variable where the length can be written.

Returns a pointer to the code buffer.

ziron_code_count [table offset: 32]

function stdcall ziron_code_count(): DWord;

Get the code buffer count.

Returns the counter of code buffers.

ziron_const_get [table offset: 36]

function stdcall ziron_const_get(DWord i): pointer;

Get a pointer to a const struct.

i ID of the const.

Returns a pointer to the const struct.

ziron_const_count [table offset: 40]

function stdcall ziron_const_count(): DWord;

Get the const count.

Returns the counter of consts.

ziron_fixup_get [table offset: 44]

function stdcall ziron_fixup_get(Pointer fn; DWord i): Pointer;

Get a pointer to a fixup struct.

fn Pointer to a function struct.
i ID of the fixup.

Returns a pointer to a fixup struct.

ziron_fixup_count [table offset: 48]

function stdcall ziron_fixup_count(Pointer fn): DWord;

Return the fixup count for specified method.

fn Pointer to a function struct.

Returns the counter of fixups for specified method.

ziron_func_get [table offset: 52]

function stdcall ziron_func_get(DWord i): Pointer;

Returns a method struct.

i ID of the method.

Returns a pointer to a method struct.

ziron_func_count [table offset: 56]

function stdcall ziron_func_count(): DWord;

Get the total amount of methods.

Returns the counter of methods.

ziron_file_writecode [table offset: 60]

procedure stdcall ziron_file_writecode(DWord i);

Writes the method buffer to the end of the file buffer.

i ID of the method.

ziron_imp_get [table offset: 64]

function stdcall ziron_imp_get(DWord ilib; DWord i): Pointer;

Info coming soon....

ziron_imp_count [table offset: 68]

function stdcall ziron_imp_count(DWord ilib): DWord;

Get the total amount of imported methods.

Returns the counter of imported methods.

ziron_ilib_count [table offset: 72]

function stdcall ziron_ilib_count(): DWord;

Get the total amount of import libraries.

Returns the counter of import libraries.

ziron_ilib_name [table offset: 76]

function stdcall ziron_ilib_name(DWord ilib): char*;

Info coming soon....

ziron_fixup_add [table offset: 80]

procedure stdcall ziron_fixup_add(FIXUP_TYPE ft; pointer func; DWord index; DWord pos; byte size; DWord ofs);

Info coming soon....

ziron_func_emit [table offset: 84]

procedure stdcall ziron_func_emit(pointer fn; pointer p; DWord len);

Info coming soon....

ziron_func_rem [table offset: 88]

procedure stdcall ziron_func_rem(Pointer fn; DWord start; DWord len);

Info coming soon....

ziron_func_exec [table offset: 92]

function stdcall ziron_func_exec(char* c; DWord len): boolean;

Info coming soon....

ziron_var_get [table offset: 96]

function stdcall ziron_var_get(DWord i): Pointer;

Info coming soon....

ziron_var_count [table offset: 100]

function stdcall ziron_var_count(): DWord;

Get the total amount of variables.

Returns the counter of variables.

ziron_set_fileext [table offset: 104]

procedure stdcall ziron_set_fileext(wchar* s);

Info coming soon....

ziron_file_getbuf [table offset: 108]

function stdcall ziron_file_getbuf(): Pointer;

Info coming soon....

ziron_file_writeresources [table offset: 112]

function stdcall ziron_file_writeresources(DWord rva): DWord;

Info coming soon....

ziron_get_flags [table offset: 116]

function stdcall ziron_get_flags(): Pointer;

Info coming soon....

ziron_register_keyword [table offset: 120]

function stdcall ziron_register_keyword(char* name; pointer callback): DWord;

Info coming soon....

ziron_unregister_keyword [table offset: 124]

function stdcall ziron_unregister_keyword(char* name): boolean;

Info coming soon....

ziron_expect_token [table offset: 128]

function stdcall ziron_expect_token(DWord tk): Int32;

Info coming soon....

ziron_expect_ident [table offset: 132]

function stdcall ziron_expect_ident(DWord id): Int32;

Info coming soon....

ziron_curtoken_size [table offset: 136]

function stdcall ziron_curtoken_size(): DWord;

Info coming soon....

ziron_token_next [table offset: 140]

function stdcall ziron_token_next(): DWord;

Info coming soon....

ziron_curtoken_int32 [table offset: 144]

procedure stdcall ziron_curtoken_int32(pointer buf);

Info coming soon....

ziron_curtoken_int64 [table offset: 148]

procedure stdcall ziron_curtoken_int64(pointer buf);

Info coming soon....

ziron_curtoken_charptr [table offset: 152]

function stdcall ziron_curtoken_charptr(): char*;

Info coming soon....

ziron_curtoken_wcharptr [table offset: 156]

function stdcall ziron_curtoken_wcharptr(): wchar*;

Info coming soon....

ziron_curtoken_real [table offset: 160]

procedure stdcall ziron_curtoken_real(pointer buf; DWord size);

Info coming soon....

ziron_token_peek [table offset: 164]

function stdcall ziron_token_peek(): DWord;

Info coming soon....

ziron_eol [table offset: 168]

function stdcall ziron_eol(): boolean;

Info coming soon....

ziron_extractline [table offset: 172]

function stdcall ziron_extractline(char* buf; int32 maxlen): int32;

Info coming soon....

ziron_token_ident [table offset: 176]

function stdcall ziron_token_ident(): Int32;

Info coming soon....

ziron_conv_labelref [table offset: 180]

function stdcall ziron_conv_labelref(): DWord;

Info coming soon....

ziron_curtoken_dataptr [table offset: 184]

function stdcall ziron_curtoken_dataptr(): pointer;

Info coming soon....

ziron_func_index [table offset: 188]

function stdcall ziron_func_index(pointer fn): DWord;

Info coming soon....

Assembly Reference

Coming soon!


Currently Active Users:
There are currently 2 user(s) online. 0 member(s) and 2 guest(s)
Most users ever online was 1046, January 28, 2022, 2:08 pm.


Statistics:
Threads: 225 | Posts: 1848 | Members: 51 | Active Members: 51
Welcome to our newest member, yecate
const Copyright = '2011-2024 © OverHertz Ltd. All rights reserved.';
Web development by OverHertz Ltd