При разработке программ полностью на ассемблере NASM с меткой _start возникает вопрос: как это удобно отлаживать? Хочется использовать мощный графический инструмент VS Code с breakpoints, step-by-step выполнением и просмотром переменных.

🚀 1. Быстрый старт

Если нужно быстро начать, вот минимальный набор действий:

extern void asm_main(void);

int main(void) {
    asm_main();
    return 0;
}

global _start
_start:

global asm_main
asm_main:

build_signed: prepare_dirs
+	gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c
 	nasm -f elf64 -g -F dwarf src/io_signed.asm -o build/io_signed.o
 	nasm -f elf64 -g -F dwarf src/signed_a.asm -o build/signed_a.o
-	ld -m elf_x86_64 -o bin/signed build/signed_a.o build/io_signed.o
+	gcc -o bin/signed build/debug_wrapper.o build/signed_a.o build/io_signed.o -m64 -no-pie -z noexecstack

💡 2. Зачем это нужно?

В чём корень проблемы?

Для VS Code не существует полнофункционального расширения, которое бы реализовывало Debug Adapter Protocol (DAP) специально для ассемблера NASM.

Debug Adapter Protocol (DAP) — это стандартный протокол, который позволяет интерфейсу VS Code “общаться” с реальными отладчиками (такими как GDB).

Поскольку нативного “Assembly-адаптера” не существует, здесь используется хитрость: расширение C/C++ от Microsoft. Оно умеет работать с GDB, но оптимизировано под стандартный C/C++ проект. Наша “чистая” ассемблерная программа с меткой _start, слинкованная через ld, не соответствует этой модели — отсюда и проблемы.

Что мы получим?

✅ Графический отладчик — визуальный интерфейс вместо консольного GDB
✅ Breakpoints — остановка выполнения на любой строке
✅ Step-by-step выполнение — пошаговая трассировка кода
✅ Просмотр переменных — значения регистров и памяти в реальном времени
✅ Call Stack — цепочка вызовов функций
✅ Watch expressions — отслеживание произвольных выражений

Для кого это актуально?

Этот метод особенно полезен при выполнении:

• Лабораторных работ №3, 4 и 5 по ассемблеру
• Собственных проектов на чистом ассемблере, например, с использованием готовых модулей ввода-вывода
• Системного программирования с прямыми системными вызовами
• Низкоуровневой разработки без использования стандартной библиотеки C

🤔 3. Какой подход выбрать?

Существует два основных способа отладки ассемблерного кода в VS Code:

В этой статье рассматривается графический подход, так как он даёт максимальное удобство для обучения и разработки. Подробнее о консольном GDB можно узнать в статье «Настройка NASM x86-64 и VS Code: Гайд для Linux и Windows».

🔧 4. Как это работает?

Архитектура решения

┌─────────────────────────────────────────────────────────┐
│                   VS Code (интерфейс)                   │
├─────────────────────────────────────────────────────────┤
│              C/C++ Extension (DAP адаптер)              │
├─────────────────────────────────────────────────────────┤
│                    GDB (отладчик)                       │
├─────────────────────────────────────────────────────────┤
│   ┌──────────────────┐      ┌────────────────────┐      │
│   │ debug_wrapper.c  │ ───▶ │  asm_main() в .asm │      │
│   │  (точка входа)   │      │  (ваш код)         │      │
│   └──────────────────┘      └────────────────────┘      │
└─────────────────────────────────────────────────────────┘

Ключевая идея

💡 Решение: временно добавляем минимальную C-обёртку, которая вызывает нашу ассемблерную функцию. Программа при этом всё равно завершается через ассемблерный код — C нужен только для старта отладчика. Для финальной версии обёртка удаляется.

Важно понимать:

1. C-обёртка НЕ управляет выполнением программы
2. Она только запускает вашу ассемблерную функцию
3. Программа завершается через syscall в ассемблерном коде
4. Весь основной код остаётся полностью на ассемблере

Два типа программ

Процесс настройки зависит от того, использует ли ваша программа параметры командной строки:

📝 5. Практика: Пошаговая настройка

Предварительные требования

Установите необходимые инструменты. Подробное пошаговое руководство по настройке окружения в Windows (WSL) и Linux доступно в статье «Настройка NASM x86-64 и VS Code: Гайд для Linux и Windows».

Краткий список:

# Установка всего необходимого
sudo apt update && sudo apt install build-essential gdb nasm -y

# Проверка установки
gcc --version
nasm --version
gdb --version

Расширения VS Code:

• C/C++ Extension Pack

Шаг 1: Конфигурация VS Code

Создайте в корне проекта папку .vscode с двумя файлами конфигурации.

Файл .vscode/tasks.json

Автоматизирует сборку проекта:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Make all",
      "type": "shell",
      "command": "make",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": ["$gcc"]
    },
    {
      "label": "Make clean",
      "type": "shell",
      "command": "make clean"
    }
  ]
}

Файл .vscode/launch.json

Вариант 1: Программы без аргументов

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "🔍 Debug",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/bin/main",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb",
      "preLaunchTask": "Make all",
      "setupCommands": [
        {
          "description": "Включить pretty-printing для gdb",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        },
        {
          "description": "Установить Intel-синтаксис",
          "text": "set disassembly-flavor intel",
          "ignoreFailures": true
        }
      ]
    }
  ]
}

Вариант 2: Программы с аргументами командной строки

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "🔍 Debug (только файл)",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/bin/main",
      "args": ["data/input.txt"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb",
      "preLaunchTask": "Make all",
      "setupCommands": [
        {
          "description": "Включить pretty-printing",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        },
        {
          "description": "Intel-синтаксис",
          "text": "set disassembly-flavor intel",
          "ignoreFailures": true
        }
      ]
    },
    {
      "name": "🔍 Debug (файл + параметры)",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/bin/main",
      "args": ["data/input.txt", "-100", "100", "5"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "externalConsole": false,
      "MIMode": "gdb",
      "preLaunchTask": "Make all",
      "setupCommands": [
        {
          "description": "Включить pretty-printing",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        },
        {
          "description": "Intel-синтаксис",
          "text": "set disassembly-flavor intel",
          "ignoreFailures": true
        }
      ]
    }
  ]
}

💡 Настройте под свой проект: Измените значения в массиве args и путь к исполняемому файлу в program в соответствии с вашими требованиями.

Шаг 2: Создайте C-обёртку

Создайте файл src/debug_wrapper.c:

// src/debug_wrapper.c
extern void asm_main(void);

int main(void) {
    asm_main();
    // Программа завершится внутри asm_main через syscall
    return 0;  // Эта строка не выполнится
}

// src/debug_wrapper.c
extern void asm_main(int argc, char** argv);

int main(int argc, char** argv) {
    asm_main(argc, argv);
    // Программа завершится внутри asm_main через syscall
    return 0;  // Эта строка не выполнится
}

⚠️ Важно: C-обёртка НЕ управляет завершением программы. Она только запускает вашу ассемблерную функцию, которая сама завершит выполнение через syscall.

Шаг 3: Измените точку входа в .asm файле

Для всех программ замените _start на asm_main:

section .text
    global _start

_start:
    ; === Ваш код ===
    call read_input
    call process_data
    call print_output
    
    mov rax, 60
    xor rdi, rdi
    syscall

section .text
    global asm_main

asm_main:
    ; === Ваш код БЕЗ ИЗМЕНЕНИЙ ===
    call read_input
    call process_data
    call print_output
    
    mov rax, 60         ; sys_exit - оставляем!
    xor rdi, rdi
    syscall             ; Программа завершится здесь

🚨 Критически важно:

• Меняется только global _start → global asm_main и метка _start: → asm_main:
• syscall для выхода ОСТАЁТСЯ! Не заменяйте его на ret
• Весь остальной код остаётся АБСОЛЮТНО без изменений

Шаг 4: Специальная адаптация для программ с аргументами

Если ваша программа использует аргументы командной строки (argc, argv), требуется дополнительное изменение: адаптация получения аргументов.

Почему это необходимо?

Это различие фундаментально и регулируется соглашением о вызовах System V ABI. Детальное описание ролей регистров (RDI, RSI, RDX и т.д.) можно найти в «Шпаргалка NASM x86-64: Регистры, Инструкции, Syscalls (Linux)».

_start:
    pop rax        ; argc
    pop rbx        ; argv[0]
    pop rdi        ; argv[1]

asm_main:
    ; rdi = argc, rsi = argv
    mov r8, [rsi + 8]   ; argv[1]

Визуальное сравнение

╔═══════════════════════════════════════════════════════════════╗
║                      ДОСТУП К АРГУМЕНТАМ                      ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  Через _start (стек):              Через asm_main (регистры): ║
║  ┌─────────────┐                   ┌─────────────┐            ║
║  │ [rsp] = 3   │ ← argc            │ rdi = 3     │ ← argc     ║
║  ├─────────────┤                   ├─────────────┤            ║
║  │ [rsp+8]     │ ← argv[0]         │ rsi = &argv │            ║
║  ├─────────────┤                   │             │            ║
║  │ [rsp+16]    │ ← argv[1]         │ [rsi+0]     │ ← argv[0]  ║
║  ├─────────────┤                   │ [rsi+8]     │ ← argv[1]  ║
║  │ [rsp+24]    │ ← argv[2]         │ [rsi+16]    │ ← argv[2]  ║
║  └─────────────┘                   └─────────────┘            ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Пошаговая трансформация кода

ШАГ 1: Получение argc

_start:
    pop     rax          ; Извлекаем argc из стека
    cmp     rax, 2       ; Проверяем количество аргументов
    jl      .error_usage ; Если < 2, показываем usage

asm_main:
    ; argc УЖЕ в rdi, извлекать не нужно!
    cmp     rdi, 2       ; Проверяем количество аргументов
    jl      .error_usage ; Если < 2, показываем usage

ШАГ 2: Получение argv[1] (первый аргумент)

_start:
    pop     rax      ; argc
    pop     rbx      ; argv[0] (пропускаем)
    pop     rdi      ; argv[1] (первый аргумент)

asm_main:
    ; rdi = argc
    ; rsi = argv
    
    ; Получаем argv[1] (первый аргумент)
    mov     rdi, [rsi + 8]

Таблица доступа к argv:

Критически важно: Всегда сохраняйте rsi на стеке (push rsi) перед использованием других регистров, и восстанавливайте (pop rsi), когда снова нужен доступ к argv!

Полный пример трансформации

section .data
     usage_msg db "Usage: ./program <filename>", 10
     usage_len equ $ - usage_msg

 section .text
-    global _start
+    global asm_main

-_start:
+asm_main:
+    ; При входе:
+    ; rdi = argc
+    ; rsi = argv
+    
     ; Проверка argc
-    pop     rax                       ; Извлекаем argc из стека
-    cmp     rax, 2                    ; Проверяем количество аргументов
+    cmp     rdi, 2                    ; argc УЖЕ в rdi
     jl      .show_usage
     
-    ; Получение имени файла (argv[1])
-    pop     rbx                       ; argv[0] (имя программы) - пропускаем
-    pop     rdi                       ; argv[1] (имя файла) - сохраняем в rdi
+    ; Сохраняем rsi, т.к. rdi будем использовать для файла
+    push    rsi                       ; ДОБАВЛЕНО: сохраняем указатель на argv
+    
+    ; Получение имени файла (argv[1])
+    mov     rdi, [rsi + 8]            ; ИЗМЕНЕНО: доступ через массив
     
     ; Открытие файла
     mov     rax, 2                    ; sys_open
+    push    rsi                       ; ДОБАВЛЕНО: сохраняем rsi
     xor     rsi, rsi                  ; O_RDONLY
     xor     rdx, rdx
     syscall
+    pop     rsi                       ; ДОБАВЛЕНО: восстанавливаем rsi
     
     ; Проверка ошибки открытия
     test    rax, rax
     js      .error_open
     
     ; Далее работа с файлом...
     ; (этот код остаётся БЕЗ ИЗМЕНЕНИЙ)
     
     ; Завершение (БЕЗ ИЗМЕНЕНИЙ)
     mov     rax, 60
     xor     rdi, rdi
     syscall

 .show_usage:
     mov     rax, 1
     mov     rdi, 1
     mov     rsi, usage_msg
     mov     rdx, usage_len
     syscall
     
     mov     rax, 60
     mov     rdi, 1
     syscall

 .error_open:
     mov     rax, 60
     mov     rdi, 1
     syscall

Ключевые изменения

Частые ошибки при адаптации

asm_main:
    mov     rdi, [rsi + 8]
    ; ... используем rdi для системного вызова ...
    mov     r8, [rsi + 16]    ; ❌ rsi мог быть перезаписан!

asm_main:
    push    rsi               ; Сохраняем rsi
    mov     rdi, [rsi + 8]
    ; ... используем rdi ...
    pop     rsi               ; Восстанавливаем rsi
    mov     r8, [rsi + 16]    ; ✅ Теперь безопасно

mov     rdi, [rsi + 1]    ; ❌ Смещение 1 байт, а не 8!

mov     rdi, [rsi + 8]    ; ✅ Каждый указатель = 8 байт

asm_main:
    pop     rax           ; ❌ Стек не содержит argc!

asm_main:
    ; argc УЖЕ в rdi, ничего не нужно извлекать
    cmp     rdi, 2

Чек-лист адаптации для программ с аргументами

• global _start → global asm_main
• _start: → asm_main:
• Удалить pop rax для argc → использовать rdi напрямую
• Изменить cmp rax, N → cmp rdi, N
• Удалить все pop ... для argv → использовать mov ..., [rsi + offset]
• Добавить push rsi перед использованием других регистров
• Добавить pop rsi когда снова нужен доступ к argv
• Убедиться, что смещения кратны 8: [rsi + 8], [rsi + 16], [rsi + 24]
• syscall для выхода остаётся без изменений!

Шаг 5: Модифицируйте Makefile

Изменения в Makefile идентичны для всех типов программ. Рассмотрим на примере стандартного проекта.

Предполагаемая структура проекта

Перед началом убедитесь, что структура вашего проекта выглядит так:

project/
├── src/
│   ├── debug_wrapper.c      # ← Создайте этот файл (Шаг 2)
│   └── main.asm             # Основная программа (измените _start → asm_main)
├── data/                    # Опционально: тестовые данные
│   └── test.txt
├── build/                   # Создаётся автоматически при сборке
├── bin/                     # Создаётся автоматически при сборке
└── Makefile                 # ← Модифицируйте этот файл (Шаг 5)

💡 Важно: Папки build/ и bin/ создаются автоматически при выполнении make (target prepare_dirs в Makefile).

Сравнение: Было → Стало

.PHONY: all prepare_dirs clean

all: prepare_dirs
	nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
	ld -m elf_x86_64 -o bin/main build/main.o

prepare_dirs:
	@mkdir -p build bin

clean:
	@echo "Cleaning project..."
	@rm -f build/*.o bin/*
	@echo "Done."

.PHONY: all prepare_dirs clean

all: prepare_dirs
	gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c
	nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
	gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie

prepare_dirs:
	@mkdir -p build bin

clean:
	@echo "Cleaning project..."
	@rm -f build/*.o bin/*
	@echo "Done."

Что изменилось (построчно)

1. Добавлена компиляция C-обёртки:

gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c

2. Линковка изменена с ld на gcc:

ld -m elf_x86_64 -o bin/main build/main.o

gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie

Разбор изменений:

💡 Почему debug_wrapper.o должен быть первым?

При линковке GCC ищет точку входа main() в первом объектном файле. Если поставить main.o первым, линковщик не найдёт main() и выдаст ошибку:

/usr/bin/ld: warning: cannot find entry symbol _start; defaulting to 0000000000401000

Адаптация для разных случаев

Пример для многомодульного проекта:

all: prepare_dirs
	gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c
	nasm -f elf64 -g -F dwarf src/io_module.asm -o build/io_module.o
	nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
	gcc -g -o bin/main build/debug_wrapper.o build/main.o build/io_module.o -no-pie

Пример для проекта с математической библиотекой (FPU):

all: prepare_dirs
	gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c
	nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
	gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie -lm

📌 Для FPU программ: добавлен флаг -lm для линковки с математической библиотекой.

Проверка правильности изменений

После редактирования выполните:

make clean && make

Успешная сборка выглядит так:

gcc -c -g -ggdb -o build/debug_wrapper.o src/debug_wrapper.c
nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie

Проверьте, что программа работает:

./bin/main

Частые ошибки

/usr/bin/ld: warning: cannot find entry symbol _start

gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie
                   ^^^^^^^^^^^^^^^^^^^^^ первым!

gcc -g -o bin/main build/debug_wrapper.o build/main.o -no-pie
                                                      ^^^^^^^

ls -la src/debug_wrapper.c

Сводная таблица изменений

🎯 6. Процесс отладки

Как запустить отладку

⚠️ Важное ограничение: Breakpoint’ы не работают напрямую в .asm файлах. Отладка выполняется через C-обёртку.

Шаги для запуска:

1. Откройте src/debug_wrapper.c в VS Code
2. Поставьте breakpoint (F9) на строке asm_main();
3. Нажмите F5 или выберите конфигурацию 🔍 Debug
4. Программа остановится на breakpoint’е в C-файле
5. Нажмите F11 (Step Into) — вы попадёте в ассемблерную функцию
6. Используйте F10 (Step Over) для пошагового выполнения
7. Вводите данные в DEBUG CONSOLE когда программа их запросит

Горячие клавиши

Что вы увидите

Ключевые панели:

• VARIABLES/WATCH (слева вверху) — значения переменных и регистров
• CALL STACK (слева внизу) — цепочка вызовов: main() → asm_main() → ваши функции
• DEBUG CONSOLE (внизу) — ввод/вывод программы и команды GDB
• Редактор (центр) — текущая строка выполнения (жёлтая стрелка)

🔍 7. Просмотр переменных в WATCH

Таблица типов данных

Примеры для разных типов программ

*(short *)&a
*(short *)&b
*(int *)&output

*(unsigned short *)&a
*(unsigned short *)&b
*(unsigned int *)&output

// Первые 10 элементов массива
*(long long(*)[10])&array

// Конкретный элемент
*((long long *)&array + 5)

// Счётчик элементов
*(long long *)&count

*(float *)&var_a
*(float *)&var_b
*(int *)&var_c

info float    # Все регистры FPU
print $st0    # Вершина стека FPU

💻 8. Полезные команды GDB

Вводите эти команды в DEBUG CONSOLE для расширенного контроля.

# Регистры
info registers              # Все регистры CPU
info float                  # Регистры FPU

# Память
x/10xb &array              # 10 байт в hex
x/10dw &array              # 10 слов в decimal
x/10xq &array              # 10 qwords в hex

# Работа с регистрами
print $rax                 # Значение
print/x $rax               # В hex
print/t $rax               # В binary
set $rax = 42              # Изменить

📖 Что значат эти регистры?

Если вы не помните, за что отвечает RFLAGS или RSP, загляните в раздел «🧠 2. Архитектура регистров x86-64» в «Шпаргалке NASM».

💡 Подробное руководство по GDB: «Настройка NASM x86-64 и VS Code: Гайд для Linux и Windows»

🛠️ 9. Troubleshooting

Многие проблемы, особенно Segmentation Fault при отладке, возникают из-за логических, а не синтаксических ошибок. Рекомендую ознакомиться со статьёй «Топ ошибок в NASM: Почему падает Segfault и неверные расчёты», где разобраны типичные «тихие» баги.

🔄 10. Подготовка к финальной версии

Когда отладка завершена, откатите все временные изменения:

Шаг 1: Удалите C-обёртку

rm src/debug_wrapper.c

Шаг 2: Верните _start в .asm файлах

Для всех программ:

section .text
    global asm_main

asm_main:
    ; Ваш код
    
    mov rax, 60
    xor rdi, rdi
    syscall

section .text
    global _start

_start:
    ; Ваш код БЕЗ ИЗМЕНЕНИЙ
    ; syscall остаётся как был!
    
    mov rax, 60
    xor rdi, rdi
    syscall

Шаг 3: Для программ с аргументами — верните доступ через стек

Если вы адаптировали код для asm_main, верните обратно:

asm_main:
    ; При входе: rdi = argc, rsi = argv
    cmp     rdi, 2
    jl      .error_usage
    
    push    rsi
    mov     rdi, [rsi + 8]
    ; ...

_start:
    pop     rax                       ; argc
    cmp     rax, 2
    jl      .error_usage
    
    pop     rbx                       ; argv[0]
    pop     rdi                       ; argv[1]
    ; ...

Шаг 4: Верните финальный Makefile

Для всех программ используйте ld для линковки:

all: prepare_dirs
	nasm -f elf64 -g -F dwarf src/main.asm -o build/main.o
	# другие .asm файлы...
	ld -m elf_x86_64 -o bin/main build/main.o # другие .o

prepare_dirs:
	@mkdir -p build bin

clean:
	@rm -f build/*.o bin/*

Шаг 5: Проверьте финальную сборку

make clean
make
./bin/main  # для программ без аргументов
./bin/main data/test.txt  # для программ с аргументами

🏁 11. Чеклист перед финализацией

Общий чеклист

• Удалён src/debug_wrapper.c
• Точка входа изменена с asm_main на _start
• Makefile использует ld для линковки
• syscall для выхода на месте (не заменён на ret)
• Программа собирается и работает: make clean && make
• Проверены все граничные случаи
• Код прокомментирован

Дополнительно для программ с аргументами

• Восстановлен доступ к argc/argv через стек (pop инструкции)
• Удалены push rsi / pop rsi если они были добавлены
• Проверена работа с разными вариантами аргументов
• Программа корректно обрабатывает файлы

✅ Заключение

Этот подход позволяет:

✅ Использовать современные инструменты — графический отладчик VS Code
✅ Видеть состояние программы — переменные, регистры, память
✅ Пошагово выполнять код — breakpoints, step into/over/out
✅ Быстро находить ошибки — call stack, watch expressions
✅ Соблюдать требования — финальная версия остаётся чистым ассемблером

Ключевые принципы

1. C-обёртка не управляет выполнением — она только запускает asm_main
2. Программа завершается через syscall — остаётся в ассемблерном коде
3. Для простых программ процесс минимален — только замена _start на asm_main
4. Для программ с аргументами нужна адаптация — argc/argv передаются через регистры rdi/rsi
5. Временные изменения минимальны — легко откатить перед финализацией