Repository navigation
Arquitetura
O bitwerk é um workspace Cargo (edição 2024, resolver 3) com cinco crates e um crate de fuzzing separado.
| 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
| 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 │
└──────────────┘
- A UI nunca fica à espera de um lock: envia
Commands por canalcrossbeame, em cada frame, lê o snapshot mais recente comArcSwap::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
ArcSwapsó para a memória cuja janela está aberta (Command::WatchMemory), atualizado no máximo a cada 100 ms e só quando muda.
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):
- A UI aplica-o à sua cópia do circuito.
Circuit::applyvalida tudo antes de mudar algo e devolveApplied(componentes, segmentos, nós e pinos tocados). - A UI corrige a cena no lugar com esse
Applied— a edição aparece no próprio frame. - A UI envia o mesmo
Editao 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).
-
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. -
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. -
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 + 16deltas; bus contention verificado depois de estabilizar.
Ver Simulaçã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.
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)
bitwerk — simulador de circuitos lógicos digitais para macOS · Licença MIT OR Apache-2.0 (LICENSE-MIT e LICENSE-APACHE no repositório) · A fonte de verdade é o código e o README.md do repositório; esta wiki descreve a versão 0.1.0.
Começar
Utilização
- Componentes
- Fios e junções
- Simulação
- Memória
- Macros e hierarquia
- Parts Centre
- Importação do Digital Works
- Exportação para o Digital Works
Referência técnica
Projeto