diff --git a/README-pt.md b/README-pt.md index 8fca790..277d326 100644 --- a/README-pt.md +++ b/README-pt.md @@ -7,13 +7,7 @@ [Tutorial em Vídeo (legendado)](https://youtu.be/RtKvvXgdVak?si=OtjkNxSGmRGNou67) -[Documentação para RISC-V](riscv-doc-pt.md) - -[RISC-V Cheatsheet](riscv/cheatsheet-pt.md) - -[Documentação para MIPS](mips-doc-pt.md) - -[Documentação para Sagui](sagui-doc-pt.md) +[Documentação](https://egg.gboncoffee.dev.br/docs/pt) [Contribuindo, bugs, requisição de features](CONTRIBUINDO.md) diff --git a/README.md b/README.md index d41c271..b246405 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,7 @@ [Video tutorial](https://youtu.be/RtKvvXgdVak?si=OtjkNxSGmRGNou67) -[Documentation for RISC-V](riscv-doc.md) - -[Documentation for MIPS](mips-doc.md) - -[Documentation for Sagui](sagui-doc.md) +[Documentation](https://egg.gboncoffee.dev.br/docs/en) [Contributing, bugs, feature requests](CONTRIBUTING.md) diff --git a/mips-doc-pt.md b/mips-doc-pt.md deleted file mode 100644 index 4d41b89..0000000 --- a/mips-doc-pt.md +++ /dev/null @@ -1,13 +0,0 @@ -[Read this document in English](mips-doc.md) - -# MIPS32 para o EGG - -A implementação de MIPS32 para o EGG usa a sintaxe de Assembly padrão descrita -no [README](README-pt.md). - -Para realizar uma chamada (_environment call_), o número dela é colocado no -registrador `v0` e os argumentos nos registradores `a0` e `a1`. - -Uma instrução `break` realiza a chamada BREAK. - -O programa montado é carregado no endereço `0` e o `pc` é inicializado em `0`. diff --git a/mips-doc.md b/mips-doc.md deleted file mode 100644 index 1302f13..0000000 --- a/mips-doc.md +++ /dev/null @@ -1,14 +0,0 @@ -[Ler esse documento em português](mips-doc-pt.md) - -# MIPS32 for EGG - -The MIPS32 implementation for EGG uses the standard Assembly syntax described in -the [README](README.md). - -Environment call numbers are placed in the `v0` register, and arguments are -placed in `a0` and `a1`. - -An `break` instruction will perform a BREAK call. - -The assembled program is loaded at the address `0` on the machine startup, and -the `pc` register is set to `0`. diff --git a/riscv-doc-pt.md b/riscv-doc-pt.md deleted file mode 100644 index 4179770..0000000 --- a/riscv-doc-pt.md +++ /dev/null @@ -1,30 +0,0 @@ -[Read this document in English](riscv-doc.md) - -# RISC-V IM 32 bits para o EGG - -A implementação de RISC-V para o EGG usa a sintaxe de Assembly padrão descrita -no [README](README-pt.md). Ela implementa os registradores e instruções do -conjunto base e da extensão de multiplicação descritos [nesse -documento](riscv/riscv.pdf). - -Para realizar uma chamada (_environment call_), o número dela é colocado no -registrador `a7` e os argumentos nos registradores `a0` e `a1`. - -Uma instrução `ebreak` realiza a chamada BREAK. - -Código de exemplo (escreve "Hello, World!", quebra a linha e sai): - -```asm - addi a7, zero, 3 - addi a0, zero, msg - addi a1, zero, 14 - ecall - ebreak - -msg: -#Hello, World!%0a -``` - -O programa montado é carregado no endereço `0` e o `pc` é inicializado em `0`. O -ponteiro da stack não é inicializado. Caso o programa faça uso da stack, ela -deve ser inicializada no programa. diff --git a/riscv-doc.md b/riscv-doc.md deleted file mode 100644 index 5eb61c4..0000000 --- a/riscv-doc.md +++ /dev/null @@ -1,30 +0,0 @@ -[Ler esse documento em português](riscv-doc-pt.md) - -# RISC-V IM 32 bits for EGG - -The RISC-V implementation for EGG uses the standard Assembly syntax described in -the [README](README.md). It implements the registers and instructions from the -base integer set and the multiplication extension described in -[this](riscv/riscv.pdf) document. - -Environment call numbers are placed in the `a7` register, and arguments are -placed in `a0` and `a1`. - -An `ebreak` instruction will perform a BREAK call. - -Example program (writes "Hello, World!", breaks a line and exits): - -```asm - addi a7, zero, 3 - addi a0, zero, msg - addi a1, zero, 14 - ecall - ebreak - -msg: -#Hello, World!%0a -``` - -The assembled program is loaded at the address `0` on the machine startup, and -the `pc` register is set to `0`. The stack pointer register is not initialized: -the program should initialize it if it wants to use the stack. diff --git a/riscv/cheatsheet-pt.md b/riscv/cheatsheet-pt.md deleted file mode 100644 index ff43148..0000000 --- a/riscv/cheatsheet-pt.md +++ /dev/null @@ -1,255 +0,0 @@ -# RISC-V Cheatsheet - EGG - -- [RISC-V Cheatsheet - EGG](#risc-v-cheatsheet---egg) - - [Instruções](#instruções) - - [Aritméticas](#aritméticas) - - [Extensão de multiplicação](#extensão-de-multiplicação) - - [Aritméticas com imediato](#aritméticas-com-imediato) - - [Loads (carregar valores da memória)](#loads-carregar-valores-da-memória) - - [Stores (salvar valores na memória)](#stores-salvar-valores-na-memória) - - [Branches (saltos condicionais)](#branches-saltos-condicionais) - - [Jumps (saltos incondicionais)](#jumps-saltos-incondicionais) - - [Miscelânea](#miscelânea) - - [Registradores](#registradores) - - [Sintaxe](#sintaxe) - - [Chamadas do emulador](#chamadas-do-emulador) - - [Carregar imediatos](#carregar-imediatos) - - [Manipular a stack](#manipular-a-stack) - - [Chamar funções](#chamar-funções) - - [Truques do debugger](#truques-do-debugger) - - [Ver o PC](#ver-o-pc) - - [Dump do programa](#dump-do-programa) - -## Instruções - -### Aritméticas - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----- | -| `add` | `rd`, `rs1`, `rs2` | Soma os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | Com. | -| `sub` | `rd`, `rs1`, `rs2` | Subtrai os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | Com. | -| `xor` | `rd`, `rs1`, `rs2` | Realiza o OU EXCLUSIVO entre os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | | -| `or` | `rd`, `rs1`, `rs2` | Realiza o OU lógico entre os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | | -| `and` | `rd`, `rs1`, `rs2` | Realiza o E lógico entre os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | | -| `sll` | `rd`, `rs1`, `rs2` | Realiza um shift lógico para a esquerda do valor de `rs1` pelo valor de `rs2`, guardando o resultado em `rd`. | | -| `srl` | `rd`, `rs1`, `rs2` | Realiza um shift lógico para a direita do valor de `rs1` pelo valor de `rs2`, guardando o resultado em `rd`. | | -| `sra` | `rd`, `rs1`, `rs2` | Realiza um shift aritmético para a direita do valor de `rs1` pelo valor de `rs2`, guardando o resultado em `rd`. | | -| `slt` | `rd`, `rs1`, `rs2` | Compara os valores de `rs1` e `rs2`. O resultado guardado em `rd` é 1 caso `rs1` < `rs2`, e 0 caso contrário. | Com. | -| `sltu` | `rd`, `rs1`, `rs2` | Igual à `slt`, porém considera os valores sem sinal. | Sem. | - -#### Extensão de multiplicação - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ---------------------------------------------------------------------------------------- | ------ | -| `mul` | `rd`, `rs1`, `rs2` | Multiplica os valores de `rs1` e `rs2`, guardando o resultado em `rd`. | Com. | -| `mulh` | `rd`, `rs1`, `rs2` | Multiplica os valores de `rs1` e `rs2`, guardando a parte alta do resultado em `rd`. | Com. | -| `mulsu` | `rd`, `rs1`, `rs2` | Igual à `mulh`, porém considera o valor de `rs1` COM SINAL e o valor de `rs2` SEM SINAL. | Misto. | -| `mulu` | `rd`, `rs1`, `rs2` | Igual à `mulh`, porém considera os valores sem sinal. | Sem. | -| `div` | `rd`, `rs1`, `rs2` | Divide o valor de `rs1` pelo valor de `rs2`, guardando o resultado em `rd`. | Com. | -| `divu` | `rd`, `rs1`, `rs2` | Igual à `div`, porém considera os valores sem sinal. | Sem. | -| `rem` | `rd`, `rs1`, `rs2` | Guarda em `rd` o resto da divisão do valor de `rs1` pelo valor de `rs2`. | Com. | -| `remu` | `rd`, `rs1`, `rs2` | Igual à `rem`, porém considera os valores sem sinal. | Sem. | - -### Aritméticas com imediato - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ------------------------------------------------------------------------------------------------------------ | ----- | -| `addi` | `rd`, `rs1`, `imm` | Soma o valor de `rs1` com o `imm`, guardando o resultado em rd. | Com. | -| `xori` | `rd`, `rs1`, `imm` | Realiza o OU EXCLUSIVO entre o valor de `rs1` e o `imm`, guardando o resultado em rd. | | -| `ori` | `rd`, `rs1`, `imm` | Realiza o OU lógico entre o valor de `rs1` e `imm`, guardando o resultado em rd. | | -| `andi` | `rd`, `rs1`, `imm` | Realiza o E lógico entre o valor de `rs1` e `imm`, guardando o resultado em rd. | | -| `slli` | `rd`, `rs1`, `imm` | Realiza um shift lógico para a esquerda do valor de `rs1` pelo `imm`, guardando o resultado em rd. | | -| `srli` | `rd`, `rs1`, `imm` | Realiza um shift lógico para a direita do valor de `rs1` pelo `imm`, guardando o resultado em rd. | | -| `srai` | `rd`, `rs1`, `imm` | Realiza um shift aritmético para a direita do valor de `rs1` pelo `imm`, guardando o resultado em rd. | | -| `slti` | `rd`, `rs1`, `imm` | Compara o valor de `rs1` com o `imm`. O resultado guardado em rd é 1 caso `rs1` < `imm`, e 0 caso contrário. | Com. | -| `sltiu` | `rd`, `rs1`, `imm` | Igual à `slt`, porém considera os valores sem sinal. | Sem. | - -### Loads (carregar valores da memória) - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ------------------------------------------------------------------------- | ----- | -| `lb` | `rd`, `rs1`, `imm` | Carrega 1 byte do endereço dado por `rs1 + imm` na região baixa de `rd`. | Com. | -| `lh` | `rd`, `rs1`, `imm` | Carrega 2 bytes do endereço dado por `rs1 + imm` na região baixa de `rd`. | Com. | -| `lw` | `rd`, `rs1`, `imm` | Carrega 4 bytes do endereço dado por `rs1 + imm` no `rd`. | | -| `lbu` | `rd`, `rs1`, `imm` | Igual à `lb` porém não extende o sinal do valor carregado. | Sem. | -| `lhu` | `rd`, `rs1`, `imm` | Igual à `lh` porém não extende o sinal do valor carregado. | Sem. | - -### Stores (salvar valores na memória) - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ----------------------------------------------------------------------- | ----- | -| `sb` | `rd`, `rs1`, `imm` | Salva o byte da região baixa de `rs1` no endereço dado por `rd + imm`. | | -| `sh` | `rd`, `rs1`, `imm` | Salva 2 bytes da região baixa de `rs1` no endereço dado por `rd + imm`. | | -| `sw` | `rd`, `rs1`, `imm` | Salva o valor de `rs1` no endereço dado por `rd + imm`. | | - -### Branches (saltos condicionais) - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------- | --------------------------------------------------- | ----- | -| `beq` | `rs1`, `rs2`, `imm` | Salta para `PC + imm` caso `rs1 == rs2`. | | -| `bne` | `rs1`, `rs2`, `imm` | Salta para `PC + imm` caso `rs1 != rs2`. | | -| `blt` | `rs1`, `rs2`, `imm` | Salta para `PC + imm` caso `rs1 < rs2`. | Com. | -| `bge` | `rs1`, `rs2`, `imm` | Salta para `PC + imm` caso `rs1 >= rs2`. | Com. | -| `bltu` | `rs1`, `rs2`, `imm` | Igual à `blt` porém realiza a comparação sem sinal. | Sem. | -| `bgeu` | `rs1`, `rs2`, `imm` | Igual à `bge` porém realiza a comparação sem sinal. | Sem. | - -### Jumps (saltos incondicionais) - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ------------------ | ------------------------------------------------------------------------ | ----- | -| `jal` | `rd`, `imm` | Salta para `PC + imm`, salvando o valor de `PC + 4` em `rd`. | Com. | -| `jalr` | `rd`, `rs1`, `imm` | Salta para o valor de `rs1 + imm`, salvando o valor de `PC + 4` em `rd`. | Com. | - -### Miscelânea - -| Mnemônico | Argumentos | Descrição | Sinal | -| --------- | ----------- | --------------------------------------------------------------------------------------- | ----- | -| `lui` | `rd`, `imm` | Carrega o valor `imm << 12` em `rd`. | | -| `auipc` | `rd`, `imm` | Carrega o valor `PC + (imm << 12)` em `rd`. | | -| `ecall` | | Realiza uma chamada ao emulador. (ver seção de chamadas) | | -| `ebreak` | | Equivalente à `ecall`, porém não considera argumentos, realiza sempre uma chamada BREAK | | - -## Registradores - -Registradores salvos devem ter seu valor original restaurado pela função que os utilizou. - -| Registrador(es) | Nome(es) | Função | Salvo(s)? | -| --------------- | ------------ | --------------------------------------------- | --------- | -| `x0` | `zero` | Constante zero. Escrever nele não tem efeito. | | -| `x1` | `ra` | Endereço de retorno. Utilizado em saltos. | | -| `x2` | `sp` | Endereço da pilha (ela cresce para baixo). | | -| `x3` | `gp` | Pointeiro global. | | -| `x4` | `tp` | Pointeiro da thread. | | -| `x5` à `x7` | `t0` à `t2` | Uso geral, temporários. | | -| `x8` e `x9` | `s0` e `s1` | Uso geral, salvos. | Sim. | -| `x10` e `x11` | `a0` e `a1` | Argumentos de função e valores de retorno. | | -| `x12` à `x17` | `a2` à `a7` | Argumentos de função. | | -| `x18` à `x27` | `s2` à `s11` | Uso geral, salvos. | Sim. | -| `x28` à `x31` | `t3` à `t6` | Uso geral, temporários. | | - -## Sintaxe - -```asm - ; Um ponto e vírgula introduz comentários - addi a7, zero, 3 - addi a0, zero, msg - addi a1, zero, 14 - ecall - ebreak -msg: -#Hello, World!%0a -``` - -## Chamadas do emulador - -Coloca-se o número em 'a7' e argumentos em 'a0' e 'a1'. - -```asm - ; Sair/Parar - addi a7, zero, 1 - ecall - - ; Sair/Parar (mais simples) - ebreak - - ; Ler texto - addi a7, zero, 2 - addi a0, zero, - addi a1, zero, - ecall - - ; Imprimir texto - addi a7, zero, 3 - addi a0, zero, - addi a1, zero, - ecall -``` - -## Carregar imediatos - -```asm - ; Números menores que 12 bits (em complemento de 2). - addi , zero, - ; Exemplo: carregar o número 42 em t0 - addi t0, zero, 42 - - ; Números maiores que 12 bits - lui , - addi , , - ; Exemplo: carregar o número 0x6747 em t0 - lui t0, 0x6 - addi t0, t0, 0x747 - - ; Números maiores que 12 bits sem extensão de sinal - ; (caso em que o bit 11 é 1 porém não se quer extender o sinal) - ; Para isso, adiciona-se 1 na parte alta para assim corrigir o valor com a extensão - lui , - addi , , - ; Exemplo: carregar o número 0x5a47 em t0 - lui t0, 0x6 - addi t0, t0, 0xa47 -``` - -## Manipular a stack - -```asm - ; Inicializar - addi sp, zero, 0 - - ; "push" - addi sp, sp, -4 - sw sp, , 0 - - ; "pop" - addi sp, sp, 4 - lw , sp, -4 -``` - -## Chamar funções - -Os argumentos e retornos ficam nos registradores com letra 'a'. - -```asm - ; Chamar função "func" - jal ra, func - - ; Retornar - jalr zero, ra, 0 -``` - -Para chamar uma função mais longe que 20 bits, precisa-se construir o -endereço e então usar 'jalr': - -```asm - jalr ra, , 0 -``` - -## Truques do debugger - -### Ver o PC - -É possível utilizar o comando `print` com a expressão `#1` para ver o PC. `#1` -significa "ver uma instrução a partir do PC". Exemplo: - -``` -egg> print #1 -0xcafebabe: func: add t0 a0 a1 -``` - -Nesse exemplo, o PC está no endereço `0xcafebabe`, onde há uma etiqueta `func`, -e a instrução é um `add`, guardando a soma de `a0` e `a1` em `t0`. - -### Dump do programa - -É possível utilizar o EGG para montar um programa em Assembly e guardar em um -arquivo. Para isso, abre-se o programa no emulador e utiliza-se o seguinte -comando: - -``` -egg> dump # -``` - -Substituindo `` pelo nome que queira salvar o arquivo do -programa. Note que esse arquivo não terá nenhum formato especial: ele conterá -apenas os bytes correspondentes às instruções do programa, junto com literais -que forem adicionados. diff --git a/riscv/instructions.png b/riscv/instructions.png deleted file mode 100644 index fc902b0..0000000 Binary files a/riscv/instructions.png and /dev/null differ diff --git a/riscv/registers.png b/riscv/registers.png deleted file mode 100644 index a99bcde..0000000 Binary files a/riscv/registers.png and /dev/null differ diff --git a/riscv/riscv.pdf b/riscv/riscv.pdf deleted file mode 100644 index 309de92..0000000 Binary files a/riscv/riscv.pdf and /dev/null differ diff --git a/sagui-doc-pt.md b/sagui-doc-pt.md deleted file mode 100644 index 17c45b6..0000000 --- a/sagui-doc-pt.md +++ /dev/null @@ -1,14 +0,0 @@ -[Read this document in English](sagui-doc.md) - -# Sagui para o EGG - -Sagui é uma arquitetura fantasia de 8 bits RISC, criada pelo Dr. Marco Zanata, -professor da Universidade Federal do Paraná. A implementação no EGG possui uma -extensão: a instrução `movr r0, r0` é interpretada como uma chamada BREAK. - -Ela usa a sintaxe padrão de Assembly descrita no [README](README-pt.md). O -assembler é bem burro, infelizmente. Ele não corrige nenhum imediato de endereço -relativo, então basicamente você está por conta para computar todos os saltos -manualmente. Boa sorte. - -![Instruções do Sagui](sagui/sagui.png) diff --git a/sagui-doc.md b/sagui-doc.md deleted file mode 100644 index e83893a..0000000 --- a/sagui-doc.md +++ /dev/null @@ -1,14 +0,0 @@ -[Ler esse documento em português](sagui-doc-pt.md) - -# Sagui for EGG - -Sagui is a fantasy 8 bit RISC architecture created by Dr. Marco Zanata, -professor at Universidade Federal do Paraná. The implementation in EGG has one -extension: a instruction `movr r0, r0` is actually interpreted as a BREAK system -call. - -It uses the standard Assembly syntax described in the [README](README.md). It's -assembler is very dumb, tho. It'll not fix any relative-addressed immediate, so -basically you're on your own to compute all jumps manually. Good luck. - -![Sagui instructions](sagui/sagui.png) diff --git a/sagui/sagui.png b/sagui/sagui.png deleted file mode 100644 index c96f715..0000000 Binary files a/sagui/sagui.png and /dev/null differ