# Краткая справка.

SASM (SimpleASM) - простая среда разработки для языков ассемблера NASM, MASM, GAS, FASM с подсветкой синтаксиса и отладчиком.

В SASM Вы можете легко разрабатывать и выполнять программы, написанные на языках ассемблера NASM, MASM, GAS, FASM. Вводите код в форму и запускайте приложение. В Windows также возможен запуск приложения в отдельном окне. Входные данные указывайте в поле "Ввод". В поле "Вывод" Вы сможете увидеть результат работы программы. При этом все сообщения и ошибки компиляции будут выводиться в форму снизу. Вы можете сохранять исходный или скомпилированный (exe) код программы в файл, а также загружать свои программы из файла. Если Вы хотите прервать выполнение программы (например, при зацикливании), нажмите кнопку "Остановить".

Программа поддерживает работу с несколькими проектами – новые файлы открываются и создаются в новых вкладках. При выходе из программы текущий набор открытых файлов сохраняется. При следующем запуске Вы сможете восстановить предыдущую сессию, нажав на кнопку "Продолжить предыдущую сессию" на стартовом окне. В параметрах можно выбрать автоматическое продолжение предыдущей сессии. Также в параметрах настраивается шрифт, положение поля "Код" и текст, отображающийся при создании нового файла. Интерфейс программы доступен на разных языках.

Стандартное меню "Правка" дополнено возможностью комментирования/раскомментирования выделенного куска кода и создания/удаления отступа в 4 пробела (Tab/Shift+Tab).

Начиная с версии 2.2 добавлена возможность переназначать горячие клавиши. Файл с ними находится по пути "Linux/share/sasm/keys.ini" ("/usr/share/sasm/keys.ini" при установке) в Linux и по пути "Windows/keys.ini" ("{папка с программой при установке}/keys.ini") в Windows.

С версии 2.3 SASM поддерживает работу в двух режимах - x64 и x86, переключаться между которыми можно в настройках на вкладке "Построение". Библиотека макросов "io.inc" работает одинаково для каждого из режимов. Там же можно изменить опции ассемблера и компоновщика. Более подробная информация об этом находится в разделе "Настройка системы сборки".

В версиях программы, начиная с 3.0, Вы можете выбрать один из четырех ассемблеров NASM, MASM, GAS, FASM в настройках на вкладке "Построение". Там же выбирается ассемблер и компоновщик (путь до них Вы можете указать в соответствующих полях). Таким образом SASM можно настроить на работу с любым ассемблером, задав пути к ассемблеру и, если нужно, компоновщику и указав необходимые опции ассемблирования и компоновки. Однако отладка и подсветка синтаксиса при таком подходе могут работать не совсем правильно. Чтобы полностью реализовать поддержку нового ассемблера, нужно написать реализацию абстрактного класса Assembler по аналогии с уже реализованными ассемблерами.

Все ассемблеры (кроме MASM) включены в SASM (на Linux они должны быть установлены) и ими можно пользоваться сразу после их выбора. Ассемблер MASM невозможно включить в сборку из-за его лицензии. Чтобы им воспользоваться, Вы должны установить MASM на Ваш компьютер с сайта http://www.masm32.com/ и указать пути до ассемблера (ml.exe, путь обычно "C:/masm32/bin/ml.exe") и до компоновщика (link.exe, путь обычно "C:/masm32/bin/link.exe") в соответствующих полях на вкладке "Построение".

В SASM добавлена папка для include файлов - "Linux/share/sasm/include/" ("/usr/share/sasm/include/" при установке) в Linux и "Windows/include" ("{папка с программой при установке}/include/") в Windows. Однако для MASM эта возможность не работает - там следует указывать до include файлов абсолютные пути.

## Примеры кода

Работоспособные примеры кода для разных ассемблеров, включая примеры работы с фунциями ввода-вывода и макросами "io.inc", содержатся в папке Projects по пути, где установлен SASM (обычно C:\Program Files (x86)\SASM на Windows, /usr/share/sasm на Linux).

## Библиотека макросов "io.inc" для NASM

В SASM включена библиотека кроссплатформенных макросов ввода-вывода "io.inc". Для её использования в начале программы нужно добавить директиву %include "io.inc" (%include "io64.inc" для 64-битного ассемблера). Подробнее о ее командах Вы можете узнать здесь: http://asmcourse.cs.msu.ru/?page_id=169 или ниже.

Имя макроса | Описание макроса
PRINT_UDEC size, data PRINT_DEC size, data | Вывод числовых данных заданных параметром data в 10-чном представлении. Параметр size – число, указывающее размерность данность в байтах; допускаются значения 1, 2, 4, 8 (x64). В качестве параметра data может выступать числовая константа, символьная константа, имя переменной, имя регистра или адресное выражение (без спецификатора размера данных в памяти). Если задается регистр большего размера, то берется заданное параметром size количество младших разрядов. PRINT_UDEC интерпретирует число как беззнаковое, PRINT_DEC — как знаковое.
PRINT_HEX size, data | Аналогично предыдущему, но данные выводятся в 16-чном представлении.
PRINT_CHAR ch | Печатается символ, заданный параметром ch. В качестве параметра может выступать численная константа, символьная константа, имя переменной, имя регистра или адресное выражение (без спецификатора размера данных в памяти). Печатается всегда содержимое 8 младших разрядов.
PRINT_STRING data | Печать строки текста, оканчивающейся символом с кодом 0. В качестве параметра можно передавать строковую константу, имя переменной или адресное выражение (без спецификатора размера данных в памяти). В случае печати строковой константы, наличие символа с кодом 0 в конце строки необязательно.
NEWLINE | Макрос переводит печать на новую строку.
GET_UDEC size, data GET_DEC size, data | Ввод числовых данных в 10-чном представлении с клавиатуры. Размер вводимых данных ограничен параметром size, который задается числом (1, 2, 4, 8 (x64)). Введенные данные обрезаются соответствующим образом. Параметр data – либо имя переменной, либо имя регистра, либо адресное выражение (без спецификатора размера данных в памяти). Если задается регистр большего размера, то старшие разряды заполняются знаковым битом в случае GET_DEC и нулями в случае GET_UDEC. GET_UDEC считывает беззнаковое число, GET_DEC — знаковое. Запрещается использовать в качестве параметра регистр esp.
GET_HEX size, data | Аналогично предыдущему, но данные задаются в 16-чном представлении с префиксом 0x.
GET_CHAR data | Аналогично предыдущему, но происходит считывание одного символа, нажатие Enter не требуется. Более того, нажатие Enter будет расцениваться как ввод управляющих символов перевода строки: 0xD 0xA в ОС Windows, 0xA в ОС *nix. Если параметр – регистр, размер которого больше 1 байта, значение считанного символа будет дополнено нулями.
GET_STRING data, maxsz | Ввод последовательности символов длиной не более чем (maxsz-1). Чтение последовательности останавливается на EOF или переводе строки, причем перевод строки сохраняется в буфере. В конец считанной строки добавляется символ с кодом 0. Параметр data – либо имя переменной, либо адресное выражение (без спецификатора размера данных в памяти). Параметр maxsz – регистр или числовая константа.

При вызовах макросов значения всех регистров общего назначения не изменяются.

## Функции ввода-вывода для NASM (x86)

Наряду с макросами, другим простым вариантом ввода-вывода в NASM являются соответствующие макросам вспомогательные функции ввода-вывода, доступные в SASM (работают только для x86 NASM проектов). Для их использования необходимо объявить нужные функции с помощью директивы extern <имя функции>, а затем размещать аргументы в регистрах в соответствии с таблицей ниже и вызывать функции с помощью инструкции call. Подробнее о функциях ввода-вывода Вы можете узнать здесь: http://asmcourse.cs.msu.ru/?page_id=2611 или ниже.

Имя функции | EAX | EDX
io_get_dec io_get_udec io_get_hex | выход: число |
io_get_char | выход: символ |
io_get_string | вход: адрес | вход: размер
io_print_dec io_print_udec io_print_hex | вход: число |
io_print_char | вход: символ |
io_print_string | вход: адрес |
io_newline |  |

При вызовах функций значения регистров EBX, EBP, ESP, EDI, ESI не изменяются, значения остальных регистров могут быть изменены.

## Немного об отладчике:

В качестве отладчика в SASM используется gdb. В дистрибутиве под Windows он включен в сборку. В Linux Вы должны установить этот пакет.

Внимание! Перед отладкой проверьте – все ли функции формируют фреймы (mov ebp, esp). Это правило должно быть выполнено для всех функций, включая main.
Также если в качестве компоновщика используется gcc, то точку входа в программу следует пометить глобальной меткой main (_main для проектов x86 GAS/FASM на Windows). Если же Вы используете другой компоновщик (например, ld), то точка входа должна быть помечена меткой start. Никакие другие метки для точки входа использовать нельзя.
Код программы должен содержаться только в секции ".text" (".code" для MASM). При использовании других имен для секции кода правильная работа отладчика не гарантирована.

Отладка программ с макросами из "io.inc" также поддерживается.

Для запуска отладки надо выбрать в меню "Отладка" одноименный пункт или нажать F5 - подсветится текущая строка. Теперь Вы можете выполнять необходимые действия по отладке (см. пункт "Отладка" в меню).

Вы можете поставить точку останова (breakpoint) (F8), нажимая на номер строки, на которой необходимо приостановить выполнение отлаживаемой программы.
Команда "Продолжить" (F5) продолжает выполнение программы до точки останова или до конца.
Команда "Приостановить" (F5) приостанавливает выполнение программы (удобно, например, если программа зациклилась).
Команда "Шаг с заходом" (F11) переходит к следующей инструкции, возможно с заходом в функции.
Команда "Шаг без захода" (F10) переходит к следующей инструкции без захода в функции.
Команда "Показать регистры" (Ctrl+R) открывает окно со значениями регистров процессора.
Команда "Показать память" (Ctrl+M) открывает окно для просмотра переменных (watches) и памяти по произвольному адресу. Введя в нем имя переменной, адрес или произвольное выражение и указав размер (b - byte (1), w - word (2), d - double word (4), q - quad word (8)), в поле "Значение" Вы получите значение данного выражения. Также можно добавлять переменные из кода, нажав правой кнопкой на строке с переменной и выбрав "Просмотреть". В выражениях поддерживаются любые операторы языка C (*, &, +, -, *, /, %, !, >, &, |, <<, sizeof и др.), регистры нужно вводить с $ в начале (например, $eax). Если выражение является адресом следует установить соответствующую галочку справа. Формат вывода определяется в первом выпадающем меню (формат Smart пытается подобрать наиболее подходящий вид отображения). Доступна возможность просмотра массивов - для отображения их содержимого в поле "Размер массива" укажите количество элементов в массиве. Для удаления просмотра выражения нажмите на него правой кнопкой мыши и выберите "Удалить". В Windows при просмотре переменных из секции .rodata следует отображать их как адрес.
Значения регистров и выражений из двух предыдущих команд обновляются при выполнении переходов на другую инструкцию в программе.

Также при запуске отладчика ниже лога появится поле "Команда GDB". В него Вы можете вводить любые команды, поддерживаемые отладчиком gdb и выполнять их нажатием на соответствующую кнопку или Enter. Сами команды и результаты их выполнения будут выводиться в поле лога выше. Предыдущие введенные команды доступны по нажатию клавиш вверх/вниз. При нажатии кнопки "Выполнить" или Enter с пустой строкой будет выполнена последняя введенная команда. Результаты выполнения команд синхронизируются с отображением текущей строки в поле кода и состоянием окон, отображающих регистры и память. Доступна опция "Вывести" при включении которой результат введенного выражения сразу вводится (к команде добавляется "p ") (удобно для быстрого определения значения выражения (например, как калькулятор)). В выражениях поддерживаются любые операторы языка C (*, &, +, -, *, /, %, !, >, &, |, <<, sizeof и др.), регистры нужно вводить с $ в начале (например, $eax). Например, чтобы посмотреть, что находиться на вершине стека, можно ввести выражение "*((int *)$esp)" с включенной галочкой "Вывести" или просто набрать команду "p *((int *)$esp)".
Чтобы присвоить переменной или регистру какое-то значение, надо перед присваиванием написать "p " или выполнять присваивание в режиме "Вывести". Например, "p $eax = 5".
Вы можете набрать команду "help" для получения справки по командам gdb (на английском). Также хорошее руководство по gdb и принципам отладки в нем можно посмотреть здесь: http://www.opennet.ru/docs/RUS/gdb/ (на русском).

## Реализация:

#### Windows

В качестве ассемблера для NASM используется nasm 2.15.05, в качестве компоновщика - gcc 4.6.2 из MinGW (gcc 4.8.1 из MinGW64 в режиме x64) или ld 2.22 из MinGW (ld 2.23.2 из MinGW64 в режиме x64).
Версии компиляторов и компоновщиков подобраны с учетом рекомендуемых программ для курса "Архитектура ЭВМ и язык ассемблера" 1-го потока ВМК МГУ (http://asmcourse.cs.msu.ru/?page_id=169).
Еще в программу включен отладчик gdb версии 7.4 из пакета MinGW (gdb 7.6 из MinGW64 в режиме x64) и немного измененная с учетом требований отладки библиотека макросов ввода-вывода.

Также в SASM, начиная с версии 3.0, включены fasm 1.73.30 и gas 2.23.1 из MinGW (gas 2.23.2 из MinGW64).

Ассемблер MASM невозможно было включить в сборку из-за его лицензии. Чтобы им воспользоваться, Вы должны установить MASM на Ваш компьютер с сайта http://www.masm32.com/ и указать пути до ассемблера (ml.exe, путь обычно "C:/masm32/bin/ml.exe") и до компоновщика (link.exe, путь обычно "C:/masm32/bin/link.exe") в соответствующих полях на вкладке "Построение".

Под Windows SASM после установки сразу готов к работе.

#### Linux

Внимание! Для работы программы на Linux на Вашем компьютере должны быть установлены:

1) nasm или gas (если их планируется использовать, fasm уже включён в сборку);

2) gcc;

3) gdb (для отладки).

## Настройка системы сборки:

В SASM присутствует гибкая система сборки программ. Помимо стандартных настроек режимов и ассемблеров, можно задавать пути к ассемблерам и компоновщикам и опции для них в ручном режиме. Стандартные значения при этом могут быть восстановлены переключением на другой ассемблер/режим и обратно.

Все настройки выполняются на вкладке "Построение".

Пути к ассемблеру и компоновщику задаются в полях "Ассемблер" и "Компоновщик" соответственно.

Флажок "Не запускать компоновщик" используется, если для построения программы запускать компоновщик не нужно: ассемблер генерирует исполняемый файл. Может быть полезен, например, в одном из режимов FASM ниже.

В полях "Опции ассемблера" и "Опции компоновщика" задаются опции, передаваемые ассемблеру и компоновщику соответственно. При этом для обобщенности опций задаются переменные, которые при передачи опций ассемблеру или компоновщику будут заменены на имена соответствующих файлов.

В поле "Имя объектного файла" можно задать имя временного выходного объектного файла, на которое будет заменена переменная $PROGRAM.OBJ$. Данная опция нужна для некоторых компоновщиков, определяющих формат объектного файла по его расширению (например, golink).

Перечислим данные переменные:

$SOURCE$ | Входной файл с исходным кодом
$LSTOUTPUT$ | Выходной файл - листинг ассемблера, необходимый для целей отладки
$PROGRAM.OBJ$ | Выходной объектный файл
$MACRO.OBJ$ | Файл, используемый библиотекой макросов "io.inc" для NASM
$PROGRAM$ | Выходной исполняемый файл

Таким образом, задавая опции на вкладке "Построение" можно менять ассемблеры и компоновщики, а также устанавливать различные конфигурации сборки программ.

#### Дополнительные конфигурации компоновщиков:

Иногда необходимо использовать компоновщик ld вместо gcc (например, чтобы компилировать программы с точкой входа start).

В Windows для этого нужно заменить конец в пути к компоновщику с "MinGW/bin/gcc.exe" на "MinGW/mingw32/bin/ld.exe" ("MinGW64/bin/gcc.exe" на "MinGW64/x86_64-w64-mingw32/bin/ld.exe" для 64-битного режима).

В Linux просто заменить "gcc" на "ld".

При этом опции компоновщика следует заменить на "$PROGRAM.OBJ$ -g -o $PROGRAM$".

Также SASM частично поддерживает компоновщик golink (только сборка и запуск, отладка не поддерживается в силу особенностей компоновщика и использования GDB в качестве отладчика).

Для его включения надо указать путь к исполняемому файлу golink.exe и опции компоновки "$PROGRAM.OBJ$ /fo $PROGRAM$ /console /debug coff /entry:<YOUR ENTRY> <DLLS>".

Также следует указать в поле "Имя объектного файла" "program.obj".

#### Дополнительные конфигурации ассемблеров:

Опишем конфигурации в виде таблицы. Первый столбец указывает, для какого ассемблера конфигурация. Второй - опции ассемблера. Третий - компоновщик (стандартный gcc с его опциями, вышеописанный ld, без компоновки, link.exe для MASM с соответствующими опциями). Если текст указан в фигурных скобках, можно выбрать любой вариант из разделённых вертикальной чертой.

Ассемблер | Опции | Компоновщик
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$ | Без компоновки
MASM | /nologo /Sn /Sa /c /coff /Fo$PROGRAM.OBJ$ /Fl$LSTOUTPUT$ $SOURCE$ | link.exe

## Устранение неполадок:

Внимание! Если у Вас что-то работает не так, проверьте следующие пункты:

1) Если в качестве компоновщика используется gcc, то точку входа в программу следует пометить глобальной (global) меткой main (_main для проектов x86 GAS/FASM на Windows). Если же Вы используете другой компоновщик (например, ld), то точка входа должна быть помечена меткой start. Внимание! Никакие другие метки для точки входа использовать нельзя.

3) Перед отладкой проверьте – все ли функции формируют фреймы (mov ebp, esp или mov rbp, rsp). Это правило должно быть выполнено для всех функций, включая main. При невыполнении данного условия правильная работа отладчика не гарантирована.

4) Код программы должен содержаться только в секции ".text" (".code" для MASM). При использовании других имен для секции кода правильная работа отладчика не гарантирована.

5) Если необходимо включить в программу другой файл директивой include, его следует разместить в папке для include файлов - "Linux/share/sasm/include/" ("/usr/share/sasm/include/" при установке) в Linux и "Windows/include" ("{папка с программой при установке}/include/") в Windows. Однако, если файл не находится (MASM или какие-либо нестандартные конфигурации), то в любом случае можно указать полный путь до файла.

6) Если возникают ошибки при сборке, проверьте опции на вкладке "Построение" в настройках. Для устранения ошибок, можно попробовать установить одну из альтернативных конфигураций системы сборки из пункта "Настройка системы сборки" данного руководства. Также можно сконфигурировать SASM для работы с нестандартными ассемблерами или компоновщиками, задав пути и опции для них. Описание формата опций также находится в пункте "Настройка системы сборки".

7) Если все равно что-то не работает, но работало раньше, попробуйте воспользоваться кнопкой "Сбросить все настройки на начальные" в настройках на вкладке "Общие".

Пожелания и сообщения об ошибках отправляйте на адрес Dman1095@gmail.com или оставляйте на GitHub Issues.

Более подробную информацию, а также новые версии программы Вы можете найти на сайте http://dman95.github.io/SASM/