# 0. Documentacao Basica do Assembly

```mermaid
graph TD
    A[Programa Assembly] --> B[Seções]
    B --> C[.text: Código Executável]
    B --> D[.data: Dados Inicializados]
    B --> E[.bss: Dados Não Inicializados]
    B --> F[Outras Seções Personalizadas]
```

## **📂 Tipos de Seções em Assembly**

{% stepper %}
{% step %}

### **Seção `.text` (Código Executável)**

**Finalidade:** Contém as instruções do programa.\
**Características:**

* Somente leitura após carregamento
* Permissões: `r-x` (leitura e execução)

**Exemplo NASM (x86-64):**

```nasm
section .text
    global _start  ; Ponto de entrada (Linux)

_start:
    mov rax, 1     ; sys_write
    mov rdi, 1     ; stdout
    mov rsi, msg
    mov rdx, len
    syscall
    mov rax, 60    ; sys_exit
    xor rdi, rdi
    syscall
```

**Exemplo MIPS:**

```nasm
.text
    .globl main
main:
    li $v0, 4      ; syscall print_string
    la $a0, msg
    syscall
    li $v0, 10     ; syscall exit
    syscall
```

{% endstep %}

{% step %}

### **Seção `.data` (Dados Inicializados)**

**Finalidade:** Armazena variáveis com valores iniciais definidos.\
**Tipos Comuns:**

* `db`: Define byte (8 bits)
* `dw`: Define word (16 bits)
* `dd`: Define doubleword (32 bits)
* `dq`: Define quadword (64 bits)

**Exemplo NASM:**

```nasm
section .data
    msg db 'Olá, mundo!', 0xA  ; 0xA = newline
    len equ $ - msg             ; Calcula tamanho
    numero dd 42                ; Inteiro 32-bit
    array times 10 dd 0         ; Array de 10 zeros
```

**Exemplo MIPS:**

```nasm
.data
    msg: .asciiz "Olá, mundo!\n"
    numero: .word 42
    array: .space 40  ; 10 palavras (4 bytes cada)
```

{% endstep %}

{% step %}

### **Seção `.bss` (Dados Não Inicializados)**

**Finalidade:** Reserva espaço para variáveis sem valor inicial.\
**Vantagens:**

* Reduz tamanho do executável
* Espaço alocado em tempo de carregamento
* Inicializada com zeros pelo sistema operacional

**Exemplo NASM:**

```nasm
section .bss
    buffer resb 100     ; Reserva 100 bytes
    var resd 1          ; Reserva 1 doubleword (32-bit)
    array resq 10       ; Reserva 10 quadwords (64-bit)
```

**Exemplo MIPS:**

```nasm
.bss
    buffer: .space 100
    var: .word 0        ; Inicializado com zero
    array: .space 80    ; 10 quadwords (8 bytes cada) = 80 bytes
```

{% endstep %}

{% step %}

### **Seções Personalizadas**

**Uso Avançado:** Criar áreas com propriedades específicas.

**Exemplo (x86-64):**

```nasm
section .minha_secao progbits alloc exec write
    ; Código/dados com permissões customizadas
```

{% endstep %}
{% endstepper %}

## **🛠️ Como Compilar e Linkar**

### **🔧 Fluxo de Compilação**

```mermaid
graph LR
    A[arquivo.asm] -->|nasm/as| B[arquivo.o]
    B -->|ld/gcc| C[executável]
```

{% stepper %}
{% step %}

### **Para x86/x86-64 (NASM)**

**Compilar:**

```bash
# 64-bit
nasm -f elf64 programa.asm -o programa.o

# 32-bit
nasm -f elf32 programa.asm -o programa.o

# Com debug symbols
nasm -f elf64 -g programa.asm -o programa.o
```

**Linkar (sem libc - para syscalls diretas):**

```bash
ld programa.o -o programa
```

**Linkar (com libc - para printf, etc.):**

```bash
gcc -no-pie programa.o -o programa
```

**Linkar com segurança (stack não executável):**

```bash
ld -z noexecstack programa.o -o programa
```

{% endstep %}

{% step %}

### **Para MIPS (GNU Assembler)**

**Compilar:**

```bash
mips-linux-gnu-as programa.s -o programa.o
```

**Linkar:**

```bash
mips-linux-gnu-ld programa.o -o programa
```

**Linkar com libc:**

```bash
mips-linux-gnu-gcc programa.o -o programa
```

{% endstep %}

{% step %}

### **Para ARM (GNU Assembler)**

**Compilar:**

```bash
arm-linux-gnueabi-as programa.s -o programa.o
```

**Linkar:**

```bash
arm-linux-gnueabi-ld programa.o -o programa
```

{% endstep %}
{% endstepper %}

## **📝 Exemplo Completo (x86-64 Linux)**

```nasm
; exemplo.asm - Programa completo com seções .data, .bss e .text
section .data
    msg db "Olá, mundo!", 0xA     ; Mensagem com newline
    len equ $ - msg                ; Calcula tamanho

section .bss
    buffer resb 100                ; Buffer para entrada/saída

section .text
    global _start

_start:
    ; Escrever mensagem
    mov rax, 1                     ; sys_write
    mov rdi, 1                     ; stdout
    mov rsi, msg
    mov rdx, len
    syscall

    ; Sair com sucesso
    mov rax, 60                    ; sys_exit
    xor rdi, rdi                   ; código 0
    syscall
```

**Compilar e executar:**

```bash
nasm -f elf64 exemplo.asm -o exemplo.o
ld exemplo.o -o exemplo
./exemplo
```

## **🔍 Depuração com GDB**

**Comandos úteis:**

```bash
gdb ./programa

# Comandos básicos
(gdb) layout asm           # Mostra assembly com interface visual
(gdb) layout regs          # Mostra registradores em tempo real
(gdb) break _start         # Ponto de parada no início
(gdb) run                  # Executa até breakpoint
(gdb) si                   # Step instruction (entra em funções)
(gdb) ni                   # Next instruction (pula funções)
(gdb) info registers       # Mostra todos registradores
(gdb) info registers rax rbx rcx  # Mostra registradores específicos
(gdb) x/10x $rsp           # Examina 10 palavras hex na stack
(gdb) x/s $rsi             # Examina string no endereço em rsi
(gdb) watch *0x7fffffff    # Watchpoint em endereço específico
(gdb) continue             # Continua execução
(gdb) quit                 # Sai do GDB
```

## **⚠️ Problemas Comuns e Soluções**

| Problema                              | Causa                              | Solução                                          |
| ------------------------------------- | ---------------------------------- | ------------------------------------------------ |
| **Segmentation fault**                | Acesso inválido à memória          | Verifique endereços, use `gdb` para localizar    |
| **Undefined reference to `_start`**   | Faltou declarar ponto de entrada   | Adicione `global _start` e defina `_start:`      |
| **Syscalls não funcionam**            | Registradores incorretos           | Consulte tabela de syscalls para sua arquitetura |
| **Erro de linker: `cannot find -lc`** | libc não instalada                 | Instale `glibc-static` ou use `-nostdlib`        |
| **Texto aparece como lixo**           | String sem terminador              | Adicione `0` ou `0xA` ao final                   |
| **Loop infinito**                     | Condição de saída nunca atinge     | Verifique flags e saltos condicionais            |
| **Executável muito grande**           | Incluiu bibliotecas desnecessárias | Use `strip` para remover símbolos                |

## **📚 Referência Rápida de Diretivas**

| Diretiva (NASM)           | Diretiva (GAS)                        | Uso                                     |
| ------------------------- | ------------------------------------- | --------------------------------------- |
| `section .text`           | `.text`                               | Define seção de código                  |
| `section .data`           | `.data`                               | Define seção de dados inicializados     |
| `section .bss`            | `.bss`                                | Define seção de dados não inicializados |
| `global`                  | `.globl`                              | Torna símbolo visível externamente      |
| `equ`                     | `.equ`                                | Define constante                        |
| `resb` / `resw` / `resd`  | `.space`                              | Reserva espaço não inicializado         |
| `db` / `dw` / `dd` / `dq` | `.byte` / `.word` / `.long` / `.quad` | Define dados inicializados              |
| `times N instr`           | `.rept N` / `.endr`                   | Repete instrução N vezes                |
| `%include`                | `.include`                            | Inclui outro arquivo fonte              |

## **🎯 Boas Práticas**

### 1. **Organização**

* Mantenha `.text`, `.data` e `.bss` separados
* Comente cada seção claramente
* Use rótulos descritivos (ex: `loop_inicio`, `erro_arquivo`)

### 2. **Portabilidade**

* Use `global _start` para Linux (syscalls diretas)
* Use `main` e libc para programas que precisam de `printf`
* Evite instruções específicas de processador quando possível

### 3. **Otimização**

* Variáveis temporárias → `.bss` (não aumenta executável)
* Constantes → `.data`
* Use `times` para arrays grandes em vez de repetir valores

### 4. **Segurança**

* Nunca execute código em `.data` ou `.bss`
* Use `-z noexecstack` ao linkar para prevenir execução na stack
* Valide limites de buffers antes de escrever

### 5. **Depuração**

* Compile com `-g` para incluir símbolos de debug
* Use `strace` para monitorar syscalls
* Teste com diferentes entradas

## **📦 Ferramentas Recomendadas**

| Ferramenta   | Uso                              | Comando Exemplo              |
| ------------ | -------------------------------- | ---------------------------- |
| **NASM**     | Assembler x86/x86-64             | `nasm -f elf64 prog.asm`     |
| **GAS (as)** | Assembler GNU (ARM/MIPS)         | `mips-linux-gnu-as prog.s`   |
| **ld**       | Linker básico                    | `ld prog.o -o prog`          |
| **gcc**      | Linker com suporte a libc        | `gcc -no-pie prog.o -o prog` |
| **objdump**  | Visualizar seções                | `objdump -h programa`        |
| **readelf**  | Analisar cabeçalhos ELF          | `readelf -a programa`        |
| **gdb**      | Depurador                        | `gdb ./programa`             |
| **strace**   | Monitorar syscalls               | `strace ./programa`          |
| **nm**       | Listar símbolos                  | `nm programa`                |
| **strip**    | Remover símbolos (reduz tamanho) | `strip programa`             |

## **🌍 Exemplo Multiplataforma**

**Compilação Condicional (NASM):**

```nasm
%ifidn __OUTPUT_FORMAT__, elf64
    ; Código para Linux x86-64
    mov rax, 1
    mov rdi, 1
%elifidn __OUTPUT_FORMAT__, macho64
    ; Código para macOS
    mov rax, 0x2000004  ; sys_write no macOS
    mov rdi, 1
%endif
```

**Compilar para diferentes alvos:**

```bash
# Linux x86-64
nasm -f elf64 programa.asm -o programa.o
ld programa.o -o programa

# macOS (Intel)
nasm -f macho64 programa.asm -o programa.o
ld programa.o -o programa

# Windows (MinGW)
nasm -f win64 programa.asm -o programa.obj
ld programa.obj -o programa.exe
```

## **📌 Checklist de Compilação**

* [ ] Definir seções corretamente (`.text`, `.data`, `.bss`)
* [ ] Declarar ponto de entrada (`global _start` para syscalls, `main` para libc)
* [ ] Usar sintaxe correta para a arquitetura alvo
* [ ] Linkar com as flags apropriadas (`-no-pie` para libc)
* [ ] Testar permissões de execução (`chmod +x`)
* [ ] Verificar com `strace` para syscalls corretas
* [ ] Depurar com GDB se necessário

## **🔗 Recursos Adicionais**

### Manuais Oficiais

* **Intel SDM**: [Intel 64 and IA-32 Architectures Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html)
* **MIPS Architecture**: [MIPS Architecture Manuals](https://www.mips.com/products/architectures/)
* **ARM Architecture**: [ARM Developer Documentation](https://developer.arm.com/documentation)

### Livros e Tutoriais

* **Aprendendo Assembly** (Mente Binária) - [Link](https://mentebinaria.gitbook.io/assembly)
* **Programming from the Ground Up** - Jonathan Bartlett
* **The Art of Assembly Language** - Randall Hyde

### Ferramentas Online

* **Compiler Explorer**: [godbolt.org](https://godbolt.org/)
* **Online x86 Assembler**: [onlineasm.net](https://onlineasm.net/)
* **x86-64 Reference**: [felixcloutier.com/x86](https://www.felixcloutier.com/x86/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://0xmorte.gitbook.io/bibliadopentestbr/conceitos/programacao-e-linguagens/assembly/0.-documentacao-basica-do-assembly.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.