microasm

Microassembler CLI para geração de conteúdo da ROM de microcódigo, com suporte a múltiplos formatos de saída e integração direta com o Logisim-evolution. O projeto desenvolvido para ensino e experimentação em arquitetura e organização de computadores, nos cursos de Ciência e Engenharia de Computação da Universidade Federal do Espírito Santo (UFES)

📌 Objetivo

Ferramenta para ensino de:

• Microprogramação
• Arquitetura de computadores
• Simulação com Logisim-evolution
• Visualização de microinstruções

✨ Funcionalidades

• Conversão de arquivos .uasm com microcódigo para formatos binários
• Suporte a múltiplos formatos de saída
• Sistema de configuração flexível com fallback automático usando arquivo .json
• Saída formatada com tabelas alinhadas
• Cores ANSI no terminal (quando suportado)
• CLI completa com help contextual e versionamento

🚀 Uso

microasm <arquivo.uasm> [opções]

Onde as opções pedem ser:

| Opção | Descrição | |-------|-----------| | -c [nome_arquivo] | Caminho para config.json | | -o [nome_arquivo] | Arquivo de saída | | --format [bin/dump/fields/logisim] | Formato de saída | | -h, --help [tema] | Ajuda geral ou contextual | | -v, --version | Exibe versão |

📁 Estrutura do .uasm

Cada linha pode conter:

1. Label opcional seguido de dois-pontos
2. Sinais separados por ponto-e-vírgula
3. Uma das ACTIONS obrigatórias:
   • NEXT
   • DISPATCH
   • GOTO
   • ifZgt, ifZex, etc.

📄 Formatos de Saída

🔹 logisim (padrão) - compatível com logisim-evolution

v3.0 hex words addressed
000: 00000013
001: 0000A023

🔹 bin - binário puro

ADDR | BINARY
-----+------------------------------------------
000  | 00000000000000000000000000010011

🔹 fields - exibição dos campos do arquivo .uasm

ADDR | WORD     | FIELDS
-----+----------+--------------------------------
000  | 00000013 | [ACTION=NEXT] [ALUop=ADD]

🔹 dump

ADDR | ACTION | NEXT | SIGNALS
-----+--------+------+--------------------------
000  | NEXT   |  -   | ALUop=ADD
001  | GOTO   |  8   | -

🔹 markdown

| ADDR | ACTION | NEXT | SIGNALS |
|------|--------|------|---------|
| 0    | NEXT   | -    | ALUop=ADD |

📦 Instalação

🔹 Modo desenvolvimento

Clonar o repositório e criar link para o CLI de dentro do diretório do projeto

npm link

🔹 Modo global

npm install -g microasm

🧠 Configuração

O arquivo config.json contém informações essenciais para a correta tradução do microcódigo, tais como o tamanho da uROM (número de endereços e tamanho da palavra), especificação de sinais (nome, valores permitidos, número de bits e posição na palavra), e é carregado automaticamente na seguinte ordem:

1. Diretório do .uasm
2. Diretório atual
3. ~/.microasm/config.json
4. Config interno do projeto

Também é possível especificar manualmente:

microasm prog.uasm -c custom.json

🧪 Exemplo - Arquitetura simplificada

Este exemplo demonstra um microprograma simples com:

• unidade de controle microprogramada
• sinais básicos (ALU, registradores, PC)
• fluxo com NEXT e GOTO

📁 Estrutura

exemplo/
├── config.json
└── prog.uasm

⚙️ config.json

{
  "rom": {
    "word_size": 32,
    "address_bits": 8
  },
  "fields": {
    "NEXT_ADDRESS": {
      "start": 4,
      "size": 8
    }
  },
  "signals": {
    "ALUop": {
      "start": 12,
      "size": 4,
      "values": {
        "ADD": 0,
        "SUB": 1
      }
    },
    "Rwr": {
      "start": 16,
      "size": 2,
      "values": {
        "noWrite": 0,
        "write": 1
      }
    },
    "PCinc": {
      "start": 18,
      "size": 1,
      "values": {
        "0": 0,
        "1": 1
      }
    }
  }
}

🧾 prog.uasm

START: 
    ALUop=ADD; Rwr=write; PCinc=1 NEXT
    ALUop=ADD; PCinc=1 NEXT

DECODE:
    GOTO EXEC

EXEC:
    ALUop=SUB; Rwr=write NEXT

END:
GOTO START

▶️ Execução

ADDR | ACTION | NEXT | SIGNALS
-----+--------+------+--------------------------------
000  | NEXT   |  -   | ALUop=ADD, Rwr=write, PCinc=1
001  | NEXT   |  -   | ALUop=ADD, PCinc=1
002  | GOTO   | 3    | -
003  | NEXT   |  -   | ALUop=SUB, Rwr=write
004  | GOTO   | 0    | -

📊 Saída (logisim)

v3.0 hex words addressed
000: 00011010
001: 00010010
002: 00000030
003: 00012010
004: 00000000

👤 Autor

por Jadir Eduardo Souza Lucas

Universidade Federal do Espírito Santo