Skip to content

Importacao do Digital Works

PedroVMota edited this page Nov 13, 2026 · 2 revisions

Importação do Digital Works

O bitwerk importa circuitos (.dwm), templates (.dwt) e mapas de memória (.map) do Digital Works 3.0.5. O formato .dwm foi reconstruído lendo o executável do Digital Works como dados (nada foi executado) e verificado em todos os ficheiros do pacote oficial. O caminho inverso (gravar .dwm e .map binários) está em Exportação para o Digital Works. A documentação do formato está no repositório:

  • docs/dwm/DWM-FORMAT.md — formato .dwm / .dwt / .map (a secção 12 tem as notas do exportador);
  • docs/dwm/coverage.md — estatísticas de classes e campos nos 503 ficheiros do pacote e o que o bitwerk faz com cada um;
  • tools/dwm_parse.py — parser Python de referência usado na investigação (só biblioteca padrão; não executa nada dos ficheiros).

Como usar

Um circuito

  • File → Import Digital Works… (⌘I), ou File → Open… com um .dwm, ou arrastar um .dwm para a janela, ou na linha de comandos bitwerk circuito.dwm.
  • O resultado abre como projeto novo (depois da pergunta habitual sobre alterações por gravar). Não tem caminho: gravar pede um nome (é um Save As para .bitwerk).
  • Abre a janela Import report (com Copy as text). Na linha de comandos, --no-report esconde-a e --report força-a.
  • Na linha de comandos a importação é síncrona, por isso --run, --enter, --view… atuam sobre o resultado.

Uma pasta de macros para a biblioteca

  • Parts Centre → Import Digital Works folder…, File → Import Digital Works Folder to Library…, arrastar uma pasta para a janela, ou --import-dw-folder PASTA.
  • Importa todos os .dwm da pasta (com subpastas; até 5000 ficheiros e 8 níveis) para ~/Library/Application Support/bitwerk/Parts/Imported/…, numa thread própria, com barra de progresso e Cancel.
  • As peças com o mesmo conteúdo que já lá estão são ignoradas; os circuitos sem tags (que não são macros) ficam listados à parte.

Mapas de memória

A janela Memory Contents carrega os .map binários do Digital Works (número mágico 0xABCD), truncados ou completados com zeros como no original, e também os grava (Save… → Digital Works map (binary)…). Ver Memória.

Como funciona (crates/bw-io/src/dwm/)

1. Leitura (reader)

O ficheiro é um stream de objetos do Delphi (valores com etiquetas do TReader, coordenadas float32 sem etiqueta, objetos numerados, referências para trás), sem nomes de propriedades (os campos são posicionais). É interpretado por "programas" de leitura por classe, com uma pilha explícita (sem recursão) e limites em tudo. Suporta as versões 20, 30 e 34 e os templates .dwt. Uma classe desconhecida é um erro limpo.

2. Conversão (convert), por nível de macro

Aspeto Tratamento
Componentes Portas de 2–4 entradas, NOT, tri-state, flip-flops D (flanco ascendente) e JK (master-slave) com PRE/CLR, memória com o conteúdo, interruptores, relógios, geradores, VCC/massa, LEDs, 7 segmentos, saídas numéricas, tags e instâncias de macros, com a ordem dos pinos de cada classe.
Memória Os pinos de dados bidirecionais ligam-se às entradas D e às saídas Q tri-state (que flutuam durante a escrita).
Flip-flop RS O do Digital Works não tem relógio: fica um latch RS com C ligado a um VCC novo.
Geometria Coordenadas ÷ 5 (a grelha do Digital Works) arredondadas. A rotação não está no ficheiro: para cada componente procura-se a rotação e a posição que põem os pinos mais perto dos do original. As entradas de uma porta são emparelhadas pela posição. Onde um pino não coincide, um pequeno stub de fio liga-os.
Fios Cada TWire passa a um caminho de segmentos ortogonais (os poucos diagonais ganham um canto, horizontal primeiro); os pontos de solda são junções; pontos repetidos fundem-se e pontas soltas são podadas.
Macros Cada cópia embutida tem um hash canónico do conteúdo; cópias iguais dão uma definição e as instâncias referenciam-na (por exemplo Bus Contention: 9 cópias → 4 definições). As tags mantêm a ordem dos pinos do original. O pacote é DIL quando os pinos exteriores estão dispostos como um DIL (os 7 templates DIL .dwt são reconhecidos), senão uma caixa. O nome vem do texto mais descritivo do ícone (por exemplo "74HC00"), senão do ficheiro de datasheet.
Datasheet O caminho fica como nota no texto do datasheet da macro e nunca é aberto (não se cria doc_link).
Macros enormes Uma macro com mais de 255 pinos (só a unidade de controlo do Micro 5.dwm, com 361) é colocada diretamente no circuito do pai.
Texto Textos soltos e nomes de dispositivos passam a anotações (tamanho, cor, negrito, itálico, barra superior, rotação).
Dois condutores normais numa rede O Digital Works aceita, o bitwerk não: fica o primeiro e os outros são desligados (no relatório).
Relógio A velocidade não está no ficheiro (é uma opção global do Digital Works). Os relógios e geradores importados usam 10 ticks por meio período, ou seja 1 Hz com a velocidade por omissão (20 ticks/s).
Modo de simulação O projeto importado usa o modo Sequencial (compatível com o Digital Works). Ver Simulação.

O resultado passa pela mesma validação que um projeto .bitwerk.

3. Relatório (ImportReport)

Contagens por tipo, cópias de macros → definições e notas agrupadas em Unsupported, Warnings e Approximations, com o número de ocorrências. Nada é descartado em silêncio.

Não suportado ou aproximado

Item O que acontece
Janela Logic History Os dispositivos marcados são importados, a marcação não.
Desenhos livres (polígonos, linhas) e ícones desenhados das macros Não importados; as macros usam caixa ou DIL.
Cores dos fios Não importadas.
Velocidade do relógio Não está no ficheiro; assume-se 1 Hz.
Interruptor de dois terminais (TInteractiveSwitch) Aproximado por um buffer tri-state do lado com condutor para o outro, ativado por um interruptor novo (não há pinos bidirecionais).
Tags bidirecionais Passam a saídas tri-state.
Propriedade 201 da versão 34 (binário de significado desconhecido) Ignorada e indicada no relatório.

Resultados

  • 495/495 .dwm do pacote oficial e dos arquivos aninhados importam sem erros e gravam e reabrem como projeto.
  • O maior (Micro 5.dwm, 5,1 MB, 408 mil objetos) importa em ≈143 ms.
  • Importar a pasta inteira para a biblioteca demora ≈1,5 s (146 peças escritas, 291 duplicados, 58 circuitos que não são macros).
  • Testes de comportamento (crates/bw-sim/tests/dwm.rs): XOR feito com NAND (tabela completa), igualdade de 4 bits (256 combinações), JK master-slave feito com portas (SET, HOLD, TOGGLE, RESET; com atraso unitário falha, como esperado), contador a mostrar 1…14 em dois mostradores de 7 segmentos, a amostra de bus contention para com contenção, e os 74HC00, 74HC74, 74HC76 e 74HC125 importados como macros DIL cumprem as tabelas de verdade.

Para correr o teste do corpus completo (o pacote não está no repositório):

BITWERK_DWM_CORPUS=<pasta-com-os-dwm> cargo test --release -p bw-io --test dwm_corpus -- --nocapture

Sem a variável, o teste é ignorado (passa sem fazer nada). Com a mesma variável, whole_corpus_round_trips_through_export testa a ida e volta pela exportação (ver Exportação para o Digital Works).

Licença dos ficheiros de exemplo

As fixtures em crates/bw-io/tests/fixtures/dwm (≈570 KB) e as seeds em fuzz/seeds/load_dwm são ficheiros oficiais e sem alterações do pacote do Digital Works 3.0.5 (apenas com nomes encurtados). O Digital Works 3.0.5 é distribuído com uma licença permissiva do tipo ISC ("Copyright (c) 2014 by David John Barker": uso, cópia, modificação e distribuição livres, mantendo o aviso). O texto completo, tirado do tópico License Agreement da ajuda do pacote, e a lista dos caminhos originais estão em crates/bw-io/tests/fixtures/dwm/NOTICE e em fuzz/seeds/load_dwm/NOTICE.

Segurança

O parser .dwm trata cada ficheiro como hostil: 64 MiB, 2M objetos, 200 mil níveis de aninhamento, 256 classes, strings de 1 MiB, listas de 1M itens, 1M palavras de memória (verificadas contra os bytes que faltam antes de reservar memória), coordenadas finitas, nada depois do fim. Referências verificadas pelo tipo (uma inválida conta como nula e fica no relatório), profundidade das macros limitada a 16, ciclos recusados. Há um alvo de fuzzing (load_dwm; a exportação tem o roundtrip_dwm) e testes de mutação em stable. Ver Segurança.

Clone this wiki locally