Skip to content

Formato de Ficheiros

PedroVMota edited this page Nov 13, 2026 · 2 revisions

Formato de ficheiros

Extensão Conteúdo Módulo
.bitwerk Projeto (RON, versão atual 5) bw_io (lib.rs)
.bwmacro Uma macro com todas as dependências (versão atual 2) bw_io::bwmacro
.map Conteúdo de uma memória (texto, versão 1; lê e grava também o binário do Digital Works) bw_io::memmap
.dwm Circuito ou macro do Digital Works: importação e exportação (com perdas; versão 34 ao gravar) bw_io::dwm
.dwt Template do Digital Works (só leitura) bw_io::dwm

Todos os ficheiros são tratados como entrada hostil: tamanho limitado antes e durante a leitura, profundidade de recursão do RON limitada (64), contagens de objetos limitadas e validação estrutural completa antes de qualquer dado chegar à aplicação. Nada de um ficheiro é executado. Ver Segurança.

Projeto .bitwerk

Documento RON com cabeçalho versionado:

(
    format: "bitwerk",
    version: 5,
    name: "half adder",
    circuit: (
        components: [
            (id: (0), kind: Switch(on: false), pos: (x: 0, y: 0), rotation: R0),
            (id: (2), kind: Gate(op: Xor, inputs: 2), pos: (x: 8, y: 0), rotation: R0),
            // …
        ],
        nodes: [
            (id: (0), at: Pin((component: (0), pin: 0))),   // nó num pino
            (id: (1), at: Free((x: 4, y: 1))),              // junção ou curva
        ],
        segments: [(a: (0), b: (1)), /* … */],
        memories: [ /* conteúdo das memórias não vazias */ ],
        // opcionais: macros: [...], notes: [...], eval: Sequential
    ),
)

Elementos principais

Campo Conteúdo
components id, kind (ver Componentes), pos, rotation (R0, R90, R180, R270) e, opcionalmente, color: Some(Blue).
nodes / segments O grafo de fios (ver Fios e junções). A gravação renumera os nós de forma densa, por isso gravar → abrir → gravar dá o mesmo texto.
memories Conteúdo de cada memória não vazia, codificado por bw_core::memenc: palavras em hexadecimal, sequências iguais como valor*N, zeros finais omitidos (por exemplo "12 0*3 ab*3").
macros Tabela de definições usadas (o projeto é autossuficiente). Cada uma tem id, name, pins ((tag: (0), name: "A", dil: 0)), package (Dil(14); omitido para a caixa), datasheet, doc_link e origin (opcionais), hash (informativo, recalculado ao carregar) e body (um circuito como o da raiz).
notes Texto e estilo das anotações: (id: (4), note: (text: "Olá", height: 12, bold: true)).
eval Sequential para o modo compatível com o Digital Works; omitido para o atraso unitário.

Instâncias de macros escrevem-se kind: Macro((3)) (só o id; a forma é recalculada) e as tags kind: Tag(dir: In, tristate: false).

Histórico de versões e migrações

Versão O que trouxe Migração ao abrir
1 Portas, NOT, interruptor, relógio, LED; lógica de dois valores; fios ponto-a-ponto. Esquema é subconjunto do 2. Única diferença de comportamento: uma entrada sem fio valia 0 e agora está flutuante.
2 TriState, FlipFlop, Memory e a lista memories; quatro estados no simulador. (versões 1 e 2) Cada fio ponto-a-ponto passa a um caminho ortogonal (reto ou em L) entre os dois pinos; os vértices antigos são mantidos (canto horizontal primeiro). Fios que partilhavam um pino partilham o nó desse pino, por isso as redes são as mesmas.
3 Fios como grafo (nodes + segments). —
4 Macros (macros, Tag, Macro). Ficheiros 3 abrem sem conversão.
5 (atual) Const, SeqGen, SevenSeg, Numeric, Text + notes, modos de interruptor (Momentary, Pulse), color, eval. Tudo tem valor por omissão: ficheiros 4 abrem sem conversão.
  • Um ficheiro que declara uma versão mas usa elementos de uma versão posterior é recusado (por exemplo "versão 4" com SeqGen).
  • Versões futuras dão um erro explícito.
  • Ao gravar, tudo é escrito na versão atual.
  • Há fixtures de cada versão antiga (crates/bw-io/tests/fixtures/v1-* … v4-*), gravadas com o código da altura. Os testes verificam que abrem com os mesmos componentes e redes (comparadas com um union-find sobre os fios antigos), que os hashes das macros se mantêm e que gravam e reabrem iguais.

Gravação

A gravação é atómica: escreve um ficheiro temporário na mesma pasta e faz rename. O mesmo vale para os .dwm exportados e os .map (texto ou binário).

Macro .bwmacro

Uma definição com todas as definições que usa embutidas:

(
    format: "bitwerk-macro",
    version: 2,
    root: (2),
    macros: [ (id: (0), name: "Half adder", ...), ..., (id: (2), ...) ],
)
  • Os registos são os do formato de projeto 5. A versão 1 (registos do formato 4) continua a abrir.
  • Um ficheiro com definições que a raiz não usa é recusado.
  • Ao importar, as definições com o mesmo hash já presentes no projeto são reutilizadas e as outras recebem ids livres.
  • A leitura aplica os mesmos limites e validações que um projeto (ciclos, profundidade, tamanho achatado).

Mapa de memória .map

Ver Memória para o formato de texto bitwerk-map 1 e para os .map binários do Digital Works.

Exportação para o Digital Works (.dwm)

O .dwm é um formato de saída com perdas, não um formato de gravação do documento: Save As… com .dwm, Export as Digital Works 3.0.5 (.dwm)…, Export as Digital Works macro… e --export-dwm escrevem uma cópia e o documento continua ligado ao seu .bitwerk.

  • bw_io::dwm::export_project / export_circuit / export_macro devolvem os bytes e um ExportReport; memmap::save_dw_path grava o .map binário.
  • O escritor (dwm/writer.rs) usa os mesmos programas de campos por classe que o leitor e verifica os mesmos limites; os bytes são relidos antes de serem gravados.
  • Uma hierarquia que, com as macros copiadas por instância, passe os 2 milhões de objetos é recusada.

Ver Exportação para o Digital Works.

Limites

Limite Valor
Tamanho de um ficheiro de projeto ou .bwmacro 64 MiB
Profundidade de recursão RON 64
Componentes 1 000 000
Segmentos de fio 4 000 000
Nós de fio 4 000 000
Junções 1 000 000
Fios nos formatos antigos (1–2) 2 000 000, com 256 vértices cada
Nome do projeto 256 bytes
Memórias 4096 por projeto, até 16 384 palavras de 16 bits; texto codificado até 256 KiB
Definições de macros 4096
Profundidade de macros 16
Componentes no desenho achatado 2 000 000
Pinos por macro 255 (até 254 entradas e 254 saídas; 64 saídas tri-state)
Datasheet 64 KiB
Anotação 1 KiB e 16 linhas, sem caracteres de controlo
.map de texto 1 MiB, 4 KiB por linha

Ver também

Clone this wiki locally