SASM help

# Brief help.

SASM (SimpleASM) - simple Open Source crossplatform IDE for NASM, MASM, GAS, FASM assembly languages.

In SASM you can easily develop and execute programs, written in NASM assembly language. Enter code in form and simply run your program. Enter your input data in "Input" docking field. In "Output" field you can see the result of the execution of the program. Wherein all messages and compilation errors will be shown in the form on the bottom. You can save source or already compiled (exe) code of your program to file and load your programs from file.

SASM supports working with many opened projects – new files are opened and created in new tabs. At the exit from SASM current set of opened files saved. At the next start you can restore previous session. In settings you can set font, color scheme and initial text. SASM is translated into Russian and English. All dialog windows in SASM is docking - you can choose one of many variants of their position.

Standard "Edit" menu extended with abilities to comment/uncomment piece of source code and to create/delete indent with 4 spaces (Tab/Shift+Tab).

Starting with version 2.2 it is possible to reassign the hotkeys. File with them located on the path "Linux/share/sasm/keys.ini" ("/usr/share/sasm/keys.ini" if SASM was installed) on Linux and on the path "Windows/keys.ini" ("{folder where SASM was installed}/keys.ini") on Windows.

Starting with version 2.3 SASM supports 2 modes - x64 and x86. You can choose mode in settings on "Build" tab. "io.inc" macro library works with both modes. Also there you can change assembler and linker options. For more information about this, see "Building system settings". Starting from version 3.0 you can choose one of four assemblers - NASM, MASM, GAS, FASM in settings on "Build" tab. Also there you can choose your own assembler or linker filling path to them. Thus you can setup SASM on work with any assembler filling path to assembler and, if needed, to linker and filling options for assembling and linking. But debugging and highlighting may work little incorrectly. To realize full support of new assembler, it is needed to implement Assembler abstract class by analogy with already implemented assemblers.

All assemblers (excluding MASM) are included in SASM (on Linux they should be installed) and you can use they right away after their choice. MASM assembler can not be included in the assembly because of its license. To use it, you should install MASM on your computer from site http://www.masm32.com/ and specify path to MASM assembler (ml.exe, path usually "C:/masm32/bin/ml.exe") and to MASM linker (link.exe, path usually "C:/masm32/bin/link.exe") in according fields on "Build" tab in settings.

SASM contains folder for include files - "Linux/share/sasm/include/" ("/usr/share/sasm/include/" if SASM was installed) on Linux and on the path "Windows/include/" ("{folder where SASM was installed}/include/") in Windows. But for MASM this folder does not work - in this case you should use absolute path to include files.

## Code examples

Working code examples for various assemblers including examples of using input/output functions and "io.inc" macros are contained in Projects folder along the path where SASM is installed (usually C:\Program Files (x86)\SASM on Windows, /usr/share/sasm on Linux).

## "io.inc" macro library for NASM

SASM includes crossplatform input/output library "io.inc". To use it you need to add directive %include "io.inc" (%include "io64.inc" for x64) to the beginning of your program.

Macro name | Description
PRINT_UDEC size, data PRINT_DEC size, data | Print number data in decimal representation. size – number, giving size of data in bytes - 1, 2, 4 or 8 (x64). data must be number or symbol constant, name of variable, register or address expression without size qualifier (byte[], etc.). PRINT_UDEC print number as unsigned, PRINT_DEC — as signed.
PRINT_HEX size, data | Similarly previous, but data is printed in hexadecimal representation.
PRINT_CHAR ch | Print symbol ch. ch - number or symbol constant, name of variable, register or address expression without size qualifier (byte[], etc.).
PRINT_STRING data | Print null-terminated text string. data - string constant, name of variable or address expression without size qualifier (byte[], etc.).
NEWLINE | Print newline ('\n').
GET_UDEC size, data GET_DEC size, data | Input number data in decimal representation from stdin. size – number, giving size of data in bytes - 1, 2, 4 or 8 (x64). data must be name of variable or register or address expression without size qualifier (byte[], etc.). GET_UDEC input number as unsigned, GET_DEC — as signed. It is not allowed to use esp register.
GET_HEX size, data | Similarly previous, but data is entered in hexadecimal representation with 0x prefix.
GET_CHAR data | Similarly previous, but macro reads one symbol only.
GET_STRING data, maxsz | Input string with length less than maxsz. Reading stop on EOF or newline and "\n" writes in buffer. In the end of string 0 character is added to the end. data - name of variable or address expression without size qualifier (byte[], etc.). maxsz - register or number constant.

General purpose registers are not modified during execution of the above macros.

## Input/output functions for NASM (x86)

Another simple ability to use input/output in NASM is input/output functions corresponding to aforementioned macros (work only for x86 NASM projects). To use them you need to declare the desired functions with a directive extern <function name>, put the arguments into the registers according to the table below, and call the functions using call instruction.

Function name | EAX | EDX
io_get_dec io_get_udec io_get_hex | output: number |
io_get_char | output: character |
io_get_string | input: address | input: size
io_print_dec io_print_udec io_print_hex | input: number |
io_print_char | input: character |
io_print_string | input: address |
io_newline |  |

During execution of the above functions the values of the registers EBX, EBP, ESP, EDI, ESI do not change, the values of other registers can be changed.

## A little bit about the debugger:

As the debugger SASM used gdb. In the distribution under Windows it included in the package. In Linux, you must install this package.

Attention! Before debugging make all functions formed frames (mov ebp, esp). This rule should be done for all functions, including main.
Also, if gcc used as a linker, then the program entry point should be marked with global label main (_main for x86 GAS/FASM projects on Windows). Otherwise entry point should be marked with start label. Other labels for the entry point can not be used.
Program code should be contained only in ".text" section (".code" for MASM). If you use other names for the code section, then the debugger correct work is not guaranteed.

To run the debugger click "Debug" item in "Debug" menu or press F5. Now you can debug your program.

You can toggle breakpoint, clicking on line number or pressing F8 with cursor on line number, on which you want to suspend your program execution.
"Continue" command (F5) continues execution to breakpoint or to the end of your program.
"Pause" command (F5) pauses program execution (useful, for example, if program fixated).
"Step into" command (F11) goes to next instruction possible entering functions.
"Step over" command (F10) goes to next instruction skipping functions.
"Show registers" command (Ctrl+R) shows window with values of CPU registers.
"Show memory" command (Ctrl+M) shows window to watch variables or memory on random address. Typing name of variable, address or any expression over text "Add variable..." and size (b - byte (1), w - word (2), d - double word (4), q - quad word (8)), in "Value" field you will see value of expression. Also you can add variable from code, clicking right mouse button on line with variable and choose "Watch". In expressions you can use any operator of C language (*, &, +, -, *, /, %, !, >, &, |, <<, sizeof, etc.), registers should have $ prefix ($eax for example). If you want to watch memory on address you should check "Address" checkbox on the right. Output format is determined in the first drop-down menu (format Smart trying to choose the most suitable type of display). To watch contents of array specify the number of elements in the array in "array size" field. To remove watches click right mouse button on it and choose "Delete watch" or press Del button. In Windows watching variables from .rodata section you should display them as address.
Values of registers and expressions refreshes by jumping on next instruction.

Also when you run the debugger you see "GDB command" widget on the bottom of SASM. With its help you can perform any gdb command pressing Enter key. Commands and their results will be showed in log widget. Previous commands available by pressing up and down keys. If you press Enter with empty command, last command will be performed. Results of performing commands synchronize with current debugging line highlighting and with state of windows, which shows memory and registers. You can use "Print" option - if it is checked, result of command performing printing immediately ("p" command adds to input) (handy for a quick evaluation of the expression (for example, as a calculator)). In expressions you can use any operator of C language (*, &, +, -, *, /, %, !, >, &, |, <<, sizeof, etc.), registers should have $ prefix ($eax for example). For example, if you want to know, what is placed on top of stack, you might enter expression: "*((int *)$esp)" with "Print" checkbox checked or simply enter command "p *((int *)$esp)".
To set value to variable or register you should enter "p" before assignment operator ("p $eax = 5") or perform assignment in "Print" mode (if "Print" checkbox is checked).
Also you can enter "help" command in "GDB command" field to show gdb commands help.

## Implementation:

#### Windows

As NASM compiler used nasm 2.15.05, as linker - gcc 4.6.2 from MinGW (gcc 4.8.1 from MinGW64 in x64 mode) or ld 2.22 from MinGW (ld 2.23.2 from MinGW64 in x64 mode).

Also SASM 3.0 and greater contains fasm 1.73.30 and gas 2.23.1 from MinGW (gas 2.23.2 from MinGW64).

Also SASM contains gdb debugger from MinGW and "io.inc" macro library.

On Windows SASM is ready for work immediately after installation.

#### Linux

For correct working on Linux you should install next packages:

1) nasm or gas (if you will use they, fasm already included in SASM);

2) gcc;

3) gdb (gdb (for debugging).

## Building system settings:

SASM has flexible program building system. In addition to standard mode settings and assemblers, you can specify the path to the assembler and the linker and their options manually.

All settings are specified on "Build" tab.

Paths to the assembler and the linker are specified in according fields.

Check the "Disable linking" is used when building a program to run the linker is not necessary: the assembler generates an executable file. It may be useful, for example, in one mode in FASM below.

In the "Assembly options" and "Linking options" fields you can specify options, passed assembler and linker respectively. In options you can specify string variables, which will be replaced with the names of the respective files.

In the "Object file name" field you can specify name for temporary output object file, which replace $PROGRAM.OBJ$ variable. This option is needed for linkers which determines file format using file name extension (e.g., golink).

Let's consider such variables:

$SOURCE$ | Input file with source code
$LSTOUTPUT$ | Output file - assembler listing for debugging purposes
$PROGRAM.OBJ$ | Output object file
$MACRO.OBJ$ | File needed to NASM macro library "io.inc"
$PROGRAM$ | Output executable file

Thus, by setting options on the "Build" tab, you can change the assembler and the linker as well as set different build configurations.

#### Linker additional configurations:

Sometimes it is necessary to use the ld linker instead of gcc (for example, to compile the program with start entry point).

In Windows, it is needed to replace the end of the path to the linker from "MinGW/bin/gcc.exe" to "MinGW/mingw32/bin/ld.exe" (or "MinGW64/bin/gcc.exe" to "MinGW64/x86_64-w64-mingw32/bin/ld.exe" for 64-bit mode).

In Linux, just replace "gcc" to "ld".

This linker options should be replaced by "$PROGRAM.OBJ$ -g -o $PROGRAM$".

Also SASM partially supports golink linker (only for building and running, not for debugging).

To enable it you should specify path to golink.exe and linker options "$PROGRAM.OBJ$ /fo $PROGRAM$ /console /debug coff /entry:<YOUR ENTRY> <DLLS>".

Also it is needed to set "Object file name" to "program.obj".

#### Assembler additional configurations:

We describe the configuration in the table. The first column shows configuration's assembler. The second - assembly options. Third - linker (standard gcc with its options, the above ld, disable linking, link.exe for MASM with the appropriate options). If the text is enclosed in braces, you can choose any one of the separated by a vertical bar.

Assembler | Assembly options | Linker
NASM | -f {win32|win64|elf} $SOURCE$ -l $LSTOUTPUT$ -o $PROGRAM.OBJ$ | {gcc|ld|golink}
GAS | $SOURCE$ -o $PROGRAM.OBJ$ --{32|64} -a=$LSTOUTPUT$ | {gcc|ld}
FASM | $SOURCE$ $PROGRAM.OBJ$ -s $LSTOUTPUT$ | {gcc|ld|golink}
FASM | $SOURCE$ $PROGRAM$ -s $LSTOUTPUT$ | Disable linking
MASM | /nologo /Sn /Sa /c /coff /Fo$PROGRAM.OBJ$ /Fl$LSTOUTPUT$ $SOURCE$ | link.exe

## Troubleshooting:

If you have something does not work, check the following items:

1) If gcc used as a linker, then the program entry point should be marked with global label main (_main for x86 GAS/FASM projects on Windows). Otherwise entry point should be marked with start label.

3) Before debugging make all functions formed frames (mov ebp, esp or mov rbp, rsp). This rule should be done for all functions, including main. If this condition is not met, the correct work of the debugger is not guaranteed.

4) Program code should be contained only in ".text" section (".code" for MASM). If this condition is not met, the correct work of the debugger is not guaranteed.

5) If you want to include a file in program, it should be placed in the folder for include files - "Linux/share/sasm/include/" ("/usr/share/sasm/include/" after installation) in Linux and "Windows/include" ("{program folder after installation}/include/") in Windows. However, if above method doesn't work (MASM or any non-standard configuration), you can specify the full path to the file.

6) If errors occur during building, check the options on the "Building" tab in the settings. To correct the error, you can try to install one of the alternative configurations of the assembly from "Building system settings" in this guide. You can also configure SASM to work with non-standard assemblers, linkers by specifying the path and the options for them. Description of the format options are also located in "Building system settings" chapter.

7) If something still does not work, but worked before, try to use the "Reset all" button in the settings on the "Common" tab.

Wishes and reports send to e-mail: Dman1095@gmail.com or left on GitHub issues.

More information and new versions of SASM see on the site: http://dman95.github.io/SASM/