1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
|
Description: Adding md files for generating help html files
Upstream sources include two probably generated html files.
Status of their source is open and needs further investigation.
For now adding md files as a replacement for possibly lost sources.
(not forwarding this patch to upstream, until that is clarified)
---
Author: Judit Foglszinger <urbec@debian.org>
Forwarded: not-needed
Last-Update: 2023-06-21
--- /dev/null
+++ sasm-3.14.0+ds/help.md
@@ -0,0 +1,520 @@
+# Краткая справка.
+
+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]{#PRINT_UDEC} *size, | Вывод числовых данных заданных |
+| data* | параметром *data* в 10-чном |
+| | представлении. Параметр *size* -- |
+| [PRINT_DEC]{#PRINT_DEC} *size, | число, указывающее размерность |
+| data* | данность в байтах; допускаются |
+| | значения 1, 2, 4, 8 (x64). В |
+| | качестве параметра *data* может |
+| | выступать числовая константа, |
+| | символьная константа, имя |
+| | переменной, имя регистра или |
+| | адресное выражение (без |
+| | спецификатора размера данных в |
+| | памяти). Если задается регистр |
+| | большего размера, то берется |
+| | заданное параметром *size* |
+| | количество младших разрядов. |
+| | PRINT_UDEC интерпретирует число |
+| | как беззнаковое, PRINT_DEC --- |
+| | как знаковое. |
++-----------------------------------+-----------------------------------+
+| [PRINT_HEX]{#PRINT_HEX} *size, | Аналогично предыдущему, но данные |
+| data* | выводятся в 16-чном |
+| | представлении. |
++-----------------------------------+-----------------------------------+
+| [PRINT_CHAR]{#PRINT_CHAR} *ch* | Печатается символ, заданный |
+| | параметром *ch*. В качестве |
+| | параметра может выступать |
+| | численная константа, символьная |
+| | константа, имя переменной, имя |
+| | регистра или адресное выражение |
+| | (без спецификатора размера данных |
+| | в памяти). Печатается всегда |
+| | содержимое 8 младших разрядов. |
++-----------------------------------+-----------------------------------+
+| [PRINT_STRING]{#PRINT_STRING} | Печать строки текста, |
+| *data* | оканчивающейся символом с кодом |
+| | 0. В качестве параметра можно |
+| | передавать строковую константу, |
+| | имя переменной или адресное |
+| | выражение (без спецификатора |
+| | размера данных в памяти). В |
+| | случае печати строковой |
+| | константы, наличие символа с |
+| | кодом 0 в конце строки |
+| | необязательно. |
++-----------------------------------+-----------------------------------+
+| [NEWLINE]{#NEWLINE} | Макрос переводит печать на новую |
+| | строку. |
++-----------------------------------+-----------------------------------+
+| [GET_UDEC]{#GET_UDEC} *size*, | Ввод числовых данных в 10-чном |
+| *data* | представлении с клавиатуры. |
+| | Размер вводимых данных ограничен |
+| [GET_DEC]{#GET_DEC} *size*, | параметром *size*, который |
+| *data* | задается числом (1, 2, 4, 8 |
+| | (x64)). Введенные данные |
+| | обрезаются соответствующим |
+| | образом. Параметр *data* -- либо |
+| | имя переменной, либо имя |
+| | регистра, либо адресное выражение |
+| | (без спецификатора размера данных |
+| | в памяти). Если задается регистр |
+| | большего размера, то старшие |
+| | разряды заполняются знаковым |
+| | битом в случае GET_DEC и нулями в |
+| | случае GET_UDEC. GET_UDEC |
+| | считывает беззнаковое число, |
+| | GET_DEC --- знаковое. Запрещается |
+| | использовать в качестве параметра |
+| | регистр esp. |
++-----------------------------------+-----------------------------------+
+| [GET_HEX]{#GET_HEX} *size, data* | Аналогично предыдущему, но данные |
+| | задаются в 16-чном представлении |
+| | с префиксом 0x. |
++-----------------------------------+-----------------------------------+
+| [GET_CHAR]{#GET_CHAR} *data* | Аналогично предыдущему, но |
+| | происходит считывание одного |
+| | символа, нажатие Enter не |
+| | требуется. Более того, нажатие |
+| | Enter будет расцениваться как |
+| | ввод управляющих символов |
+| | перевода строки: 0xD 0xA в ОС |
+| | Windows, 0xA в ОС \*nix. Если |
+| | параметр -- регистр, размер |
+| | которого больше 1 байта, значение |
+| | считанного символа будет |
+| | дополнено нулями. |
++-----------------------------------+-----------------------------------+
+| [GET_STRING]{#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](https://github.com/Dman95/SASM/issues).
+
+Более подробную информацию, а также новые версии программы Вы можете
+найти на сайте <http://dman95.github.io/SASM/>
--- /dev/null
+++ sasm-3.14.0+ds/helpENG.md
@@ -0,0 +1,427 @@
+# 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]{#PRINT_UDEC} *size, | Print number *data* in decimal |
+| data* | representation. *size* -- number, |
+| | giving size of *data* in bytes - |
+| [PRINT_DEC]{#PRINT_DEC} *size, | 1, 2, 4 or 8 (x64). *data* must |
+| data* | 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]{#PRINT_HEX} *size, | Similarly previous, but data is |
+| data* | printed in hexadecimal |
+| | representation. |
++-----------------------------------+-----------------------------------+
+| [PRINT_CHAR]{#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]{#PRINT_STRING} | Print null-terminated text |
+| *data* | string. *data* - string constant, |
+| | name of variable or address |
+| | expression without size qualifier |
+| | (byte\[\], etc.). |
++-----------------------------------+-----------------------------------+
+| [NEWLINE]{#NEWLINE} | Print newline (\'\\n\'). |
++-----------------------------------+-----------------------------------+
+| [GET_UDEC]{#GET_UDEC} *size*, | Input number data in decimal |
+| *data* | representation from stdin. *size* |
+| | -- number, giving size of *data* |
+| [GET_DEC]{#GET_DEC} *size*, | in bytes - 1, 2, 4 or 8 (x64). |
+| *data* | *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]{#GET_HEX} *size, data* | Similarly previous, but data is |
+| | entered in hexadecimal |
+| | representation with 0x prefix. |
++-----------------------------------+-----------------------------------+
+| [GET_CHAR]{#GET_CHAR} *data* | Similarly previous, but macro |
+| | reads one symbol only. |
++-----------------------------------+-----------------------------------+
+| [GET_STRING]{#GET_STRING} *data, | Input string with length less |
+| maxsz* | 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\ output: number
+ io_get_udec\
+ io_get_hex
+
+ io_get_char output: character
+
+ io_get_string input: address input: size
+
+ io_print_dec\ input: number
+ io_print_udec\
+ io_print_hex
+
+ 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](https://github.com/Dman95/SASM/issues).
+
+More information and new versions of SASM see on the site:
+<http://dman95.github.io/SASM/>
|
