Skip to content

Arquitetura

PedroVMota edited this page Nov 13, 2026 · 2 revisions

Arquitetura

O bitwerk é um workspace Cargo (edição 2024, resolver 3) com cinco crates e um crate de fuzzing separado.

Crates

Crate Função Depende de
bw-core Modelo do circuito: ids, componentes, pinos, grafo de fios, macros (definições, tags, instâncias, tabela de definições), anotações, conteúdo das memórias, Edit/Applied. Só dados (serde), sem I/O, threads nem renderização. As invariantes são validadas na construção, em cada edição e na desserialização (#[serde(try_from)]). serde, thiserror
bw-sim Motor de simulação: achatamento da hierarquia (flatten.rs), compilação para uma netlist plana em struct-of-arrays (CSR para o fan-out e para os condutores de cada rede), avaliação orientada a eventos com quatro estados (logic.rs, netlist.rs) e a thread do simulador (engine.rs). bw-core, crossbeam-channel, arc-swap
bw-render Renderizador wgpu (Metal): câmara, cena com slots estáveis + R-tree, pipelines instanciadas, culling na GPU, atlas de símbolos ANSI/IEC (symbols/), shaders WGSL (src/shaders/). Independente do toolkit. bw-core, bw-io, wgpu, glam, bytemuck, rstar
bw-io Ficheiros: projeto RON v5 e migrações, .bwmacro, biblioteca de peças, .map, validação dos links de datasheet, importação e exportação do Digital Works (dwm/reader.rs lê o stream de objetos, dwm/convert.rs constrói o modelo, dwm/export.rs constrói o grafo de objetos a partir do modelo e dwm/writer.rs escreve-o com os mesmos programas de campos por classe do leitor; ver Exportação para o Digital Works). bw-core, serde, ron
bw-app Aplicação eframe/egui: painéis, canvas, ferramentas, menu nativo (muda), diálogos nativos (rfd), Parts Centre, janela de memória, hierarquia, importação e exportação do Digital Works (dwimport.rs, dwexport.rs), teste de carga e medição. Também o binário bw-icon. todos
fuzz/ Workspace separado com os alvos cargo-fuzz. bw-io
graph LR
  app[bw-app] --> core[bw-core]
  app --> sim[bw-sim]
  app --> render[bw-render]
  app --> io[bw-io]
  sim --> core
  render --> core
  render --> io
  io --> core
  fuzz[fuzz] --> io
Loading

Threads

Thread Responsabilidade
UI (principal) Event loop do winit, egui, submissão wgpu (eframe). Dona do Circuit (Arc, copy-on-write) e da Scene.
bw-sim Motor de simulação. Recebe comandos por canal e publica snapshots por ArcSwap. Nunca espera pela UI.
bw-scene Constrói a cena inteira (instâncias + R-tree) ao abrir um ficheiro, criar um circuito novo, gerar o teste de carga ou compactar; liberta cenas antigas. Pedidos coalescidos (só o mais recente é construído). As edições normais não passam por aqui.
Gerador do teste de carga Curta duração.
bw-dw-import / bw-dw-folder Curta duração: importação de um .dwm e de uma pasta (com progresso e flag de cancelamento).
bw-dw-export Curta duração: exportação para o Digital Works (construção do grafo, escrita, releitura de verificação, gravação atómica) sobre um Arc do circuito; o resultado volta por canal e a UI recolhe-o em O(1) por frame. Uma de cada vez.
                    comandos (crossbeam, sem bloqueio)
  ┌──────────────┐  Load / Edit / SetSwitch / SetView / WatchMemory /
  │  UI (main)   │  Run / Stop / Pause / Step / SetTickRate
  │ winit+egui   │ ─────────────────────────────────────────────▶ ┌──────────┐
  │ + wgpu       │                                                 │  bw-sim  │
  │              │ ◀───────── Arc<Snapshot> via ArcSwap ────────── │ (thread) │
  └──────┬───────┘   (leitura wait-free; o sim nunca espera pela UI)└──────────┘
         │ Arc<Circuit> (só cargas completas)  ▲
         ▼                                     │ Box<Scene> (instâncias + R-tree)
  ┌──────────────┐ ────────────────────────────┘
  │  bw-scene    │
  └──────────────┘

Comunicação UI ↔ simulador

  • A UI nunca fica à espera de um lock: envia Commands por canal crossbeam e, em cada frame, lê o snapshot mais recente com ArcSwap::load_full (wait-free).
  • O motor publica snapshots no máximo a cada 8 ms e pede um repaint à UI. Corre ticks em lotes de no máximo 10 000 e descarta atraso acumulado em vez de entrar em espiral.
  • Um snapshot traz os níveis já empacotados a 2 bits por rede (16 por u32), o número do tick, o estado, o erro (se houver), o mapa de condutores (partilhado por compilação) e os tempos da compilação (CompileStats).
  • O conteúdo das memórias nunca vai nos snapshots: há um segundo ArcSwap só para a memória cuja janela está aberta (Command::WatchMemory), atualizado no máximo a cada 100 ms e só quando muda.

Replay de edições

Cada alteração ao circuito é um bw_core::Edit (AddComponent, RemoveComponent, MoveComponent, SetRotation, SetKind, AddWire, RemoveSegment, MoveNode, DragSegment, SetMemoryWord, SetMemory, DefineMacro, RemoveMacro, SetColor, SetNote, SetEvalMode):

  1. A UI aplica-o à sua cópia do circuito. Circuit::apply valida tudo antes de mudar algo e devolve Applied (componentes, segmentos, nós e pinos tocados).
  2. A UI corrige a cena no lugar com esse Applied — a edição aparece no próprio frame.
  3. A UI envia o mesmo Edit ao simulador, que o aplica à cópia dele.

Como os ids são atribuídos de forma determinística (também os dos nós e segmentos, reutilizados por listas livres LIFO), as duas cópias ficam iguais sem nunca partilhar nem clonar o circuito inteiro. Só abrir um ficheiro, criar um circuito novo ou gerar o teste de carga enviam o circuito completo (Load).

O simulador agrupa as edições pendentes e recompila uma vez por lote; um Load torna obsoletos os anteriores. As edições só geométricas não recompilam (Edit::affects_netlist). Ao recompilar, o estado dos flip-flops e o conteúdo das memórias transitam por id/caminho.

Dentro de uma macro, a edição é aplicada a uma cópia do corpo e guardada como DefineMacro na raiz (ver Macros e hierarquia).

Simulador

  1. Achatamento (flatten.rs): cada definição e a raiz dão um template raso em cache pelo hash de conteúdo; a expansão junta redes entre níveis com union-find sobre handles de rede. Cada instância tem um scope (caminho) usado na vista interior e nas mensagens de erro.
  2. Compilação (netlist.rs): nós (componentes com comportamento) e condutores (pinos de saída, contíguos por nó), fan-out e condutores de cada rede em CSR.
  3. Avaliação: ciclos delta com atraso unitário (Jacobi) ou sequencial (Gauss–Seidel), escolhido como constante de compilação da função de avaliação. As redes com um só condutor não passam pela resolução de barramento. Race condition ao fim de nós + 16 deltas; bus contention verificado depois de estabilizar.

Ver Simulação.

Pipeline de renderização

Etapa Descrição
Câmara Um único uniform de 192 bytes; zoom e pan não reconstroem nada.
Cena (scene.rs) Slots estáveis: um de corpo por componente e por junção, um de fio por segmento. Instâncias de 24 bytes. Edições reescrevem só os slots sujos; os apagados vão para uma lista livre. R-tree (rstar) para picking e etiquetas, atualizada com remove/insert. Compactação em fundo quando mais de metade dos slots está livre.
Uploads Os slots sujos são juntos em blocos e só esses bytes são enviados. Uma cena nova é enviada em fatias de 1 MiB por frame (streaming), desenhando o que já chegou.
Níveis 2 bits por slot de sinal num storage buffer; a UI converte rede → slot uma vez por compilação.
Culling na GPU (cull.wgsl) Compute shader em três passos (contar por workgroup, soma de prefixos, escrever) que compacta os slots visíveis, agrupados por tipo (bucket), e preenche os argumentos de draw_indirect. A lista é calculada para uma região com margem e reutilizada enquanto a vista lá couber. Submetido num command buffer próprio.
Desenho Número constante de chamadas: grelha + fios + uma chamada draw_indirect por bucket de símbolos (24 buckets: tipos de componente, junções, tags, macros, …). Abaixo de 5 px físicos por unidade de grelha, um quadrado por corpo.
Símbolos (symbols/) Geometria vetorial em código (ANSI/IEEE 91 e IEC 60617), tesselada uma vez (ear clipping e faixas com miter, feitos à mão) para um atlas estático (≈271 mil vértices, ≈6 MiB): uma malha por tipo × variante × estilo. Traços nítidos em qualquer zoom (extrusão no vertex shader). Macros e anotações são acrescentadas ao atlas quando aparecem. O mesmo atlas serve a paleta (egui) e o ícone da app.
Shaders common.wgsl, grid.wgsl, wire.wgsl, body.wgsl, instances.wgsl, symbol.wgsl, cull.wgsl.

Estado sem mudar malhas: LED aceso, posição do interruptor, onda do relógio, segmentos e algarismos vêm dos níveis de 2 bits; cada vértice tem uma camada (sempre / só a 1 / só fora de 1) resolvida no shader.

Repaint a pedido: sem alterações a app não desenha nada. Com a janela tapada ou minimizada, os redesenhos pedidos ficam espaçados de pelo menos 250 ms.

Estrutura do repositório

bitwerk/
├── Cargo.toml            # workspace, lints, perfil release
├── rust-toolchain.toml   # stable
├── deny.toml             # cargo-deny
├── clippy.toml, rustfmt.toml
├── Makefile
├── crates/
│   ├── bw-core/          # modelo (+ tests/wiring.rs)
│   ├── bw-sim/           # motor (+ tests: sim, components, macros, library, dwm, dwm_export)
│   ├── bw-render/        # renderizador (+ shaders WGSL, símbolos, testes GPU)
│   ├── bw-io/            # ficheiros, library/*.bwmacro, src/dwm, tests/fixtures
│   └── bw-app/           # aplicação eframe (+ bin/bw-icon.rs)
├── assets/               # AppIcon.icns, AppIcon-256.png, Info.plist
├── examples/             # half-adder, all-components, flipflops-memory, bus-contention, macros-demo
├── docs/dwm/             # formato .dwm / .dwt / .map e cobertura
├── tools/dwm_parse.py    # parser Python de referência (também lê as exportações nos testes)
├── LICENSE-MIT, LICENSE-APACHE
└── fuzz/                 # cargo-fuzz (workspace separado)

Clone this wiki locally