Skip to content

Macros e Hierarquia

PedroVMota edited this page Nov 13, 2026 · 2 revisions

Macros e hierarquia

Uma macro é um circuito reutilizável com interface própria. No Digital Works, as macros embutidas eram copiadas para dentro de cada circuito (editar a macro não mudava as instâncias); por isso, ao exportar para o Digital Works, cada instância leva uma cópia da definição. No bitwerk as instâncias referenciam a definição: editar a definição atualiza todas as instâncias.

Conceitos (bw_core::macros)

Termo Significado
Definição (MacroDef) Um circuito (o corpo) mais uma interface: nome, pinos (criados pelas tags do corpo), ordem dos pinos, modelo visual (caixa ou DIL), datasheet em texto/Markdown e, opcionalmente, um link para um ficheiro local.
Tag Componente Tag { dir: In | Out, tristate } dentro do corpo, com um pino. A In conduz a rede interior a partir do pino da instância; a Out lê-a. Uma Out tri-state torna essa saída da instância tri-state (pode formar barramento).
Instância Componente Macro(...) que referencia a definição pelo MacroId (estável). A forma (entradas, saídas, largura, máscara tri-state, DIL) é derivada da definição; no ficheiro só vai o id.
Tabela de definições (MacroTable) Vive no circuito raiz, partilhada por Arc. Cada entrada guarda a definição, a forma das instâncias, o hash de conteúdo (FNV-1a de 64 bits sobre nome, interface, modelo, datasheet e corpo; as macros aninhadas entram pelo hash delas), o tamanho achatado e a profundidade.

Toda a alteração de uma definição é um Edit::DefineMacro (e Edit::RemoveMacro para uma definição sem uso). Se a interface muda, os pinos de cada instância são reassociados pela tag (o pino da tag X continua a ser o pino da tag X mesmo que mude de posição); os fios de pinos que desapareceram (ou mudaram de sentido ou de tri-state) são desligados. As definições que contêm a macro mudada são atualizadas em cascata.

Criar macros

A partir de uma seleção

Macro → Create Macro from Selection… (⇧⌘M), menu de contexto, botão da paleta ou das propriedades.

  1. Selecione os componentes: arrastar no vazio desenha uma caixa (com Shift junta), Shift-clique junta/retira.
  2. Dê um nome à macro.
  3. Os componentes passam para uma definição nova e no lugar deles fica uma instância.

Detalhes:

  • As redes inteiramente dentro da seleção são copiadas com a geometria.
  • Cada rede que atravessa a fronteira passa a ser uma tag: In se é conduzida de fora (ou não tem condutor), Out se é conduzida dentro (tri-state se todos os condutores de dentro o são).
  • Os nomes vêm do pino ligado quando têm significado (D, CLR, Q, QN, A0…), senão A, B, … para entradas e Y0, Y1, … para saídas.
  • Um barramento conduzido dos dois lados da fronteira é recusado (não há pinos bidirecionais).
  • Os fios criados são Ls simples e podem cruzar componentes.

Definição vazia

Macro → New Macro (ou New na secção Macros da paleta) cria uma definição vazia e abre-a. Ponha componentes e tags (paleta, secção Macros) e coloque depois instâncias a partir do Parts Centre.

Propriedades da macro

Selecione uma instância, ou clique no vazio dentro de uma definição aberta:

  • Nome (até 64 bytes).
  • Pinos: ordem (botões up/dn, dentro das entradas e das saídas) e nomes (até 12 bytes).
  • Modelo: Box (caixa automática dimensionada pelos pinos, nomes dos pinos por dentro e nome ao centro) ou DIL 8/14/16/18/20/24/28 com o número de cada pino (Auto-assign preenche os que faltam; os pinos do pacote sem sinal aparecem como stubs curtos), com pré-visualização ao vivo.
  • Datasheet (texto/Markdown, até 64 KiB) e ficheiro de datasheet opcional.
  • Exportar: Export .bwmacro… (formato próprio, com as dependências) e Export as Digital Works macro… (um .dwm do Digital Works 3.0.5 cuja interface são as tags; num modelo DIL os pinos seguem a ordem DIL). A exportação para o Digital Works perde os nomes dos pinos (as tags mostram o número), o texto do datasheet (fica só o caminho do ficheiro) e o link, e copia as macros aninhadas para dentro de cada instância. Ver Exportação para o Digital Works.
  • As alterações ficam num rascunho e aplicam-se com Apply (um único DefineMacro). Com mais de uma instância aparece o aviso de que a alteração afeta todas.

Abrir o ficheiro de datasheet

O ficheiro só é aberto depois de um clique explícito em Open datasheet file, e só se bw_io::datasheet::resolve_link o aceitar: caminho local (absoluto ou relativo à pasta do projeto), nunca um URL; canonicalizado; ficheiro regular; extensão pdf, html, htm, txt ou md; sem permissão de execução. A app corre então /usr/bin/open <caminho> sem shell. Ver Segurança.

Navegar na hierarquia

  • Entrar: duplo clique numa instância, menu de contexto → Edit Macro (open inside), ou ⌘E. A definição abre no lugar.
  • Breadcrumbs: root › Decade counter#3 › …, cada nível clicável, com Up one level (⌘↑) e o aviso "Editing the definition: changes affect all N instances" (N conta as instâncias em todos os níveis). Os nomes dos pinos aparecem junto das tags.
  • Estado ao vivo: com a simulação a correr, o interior mostra o estado dessa instância (a UI envia Command::SetView com o caminho aberto). Uma definição aberta sem instância (New Macro, Parts Centre → Open) não tem estado ao vivo.
  • Editar dentro aplica-se à definição: a edição é feita numa cópia do corpo e guardada com DefineMacro; todas as instâncias seguem. Se for recusada (ciclo, limite), é desfeita.
  • Clicar num interruptor dentro de uma macro muda a definição (todas as instâncias).
  • Subir é imediato (a cena da raiz fica guardada).
  • O conteúdo das memórias só se edita no nível raiz.

Limites

Limite Valor
Profundidade de aninhamento 16
Componentes primitivos no desenho completamente achatado 2 000 000 (trava "bombas de macros")
Definições por projeto 4096
Entradas / saídas por macro até 254 cada, 255 pinos ao todo
Saídas tri-state só as primeiras 64
Nome da macro / nome de pino / datasheet 64 bytes / 12 bytes / 64 KiB
Ciclos (A contém B contém A) recusados

Os limites são verificados ao definir, ao colocar instâncias e ao carregar; uma edição recusada não muda nada. Os limites largos de pinos existem por causa das peças importadas do Digital Works (um descodificador 7 → 128, uma ALU de 38 entradas); o editor de macros continua pensado para macros pequenas.

Simulação e desenho

  • A hierarquia é achatada na compilação (bw_sim::flatten): cada definição dá um template raso em cache pelo hash de conteúdo, e a expansão junta as redes entre níveis com union-find. Simular não tem custo de hierarquia.
  • O estado dos flip-flops e das memórias passa entre compilações pelo caminho completo (instâncias + id).
  • As instâncias são desenhadas com o seu modelo pelo mesmo caminho com culling na GPU; a malha de cada definição é acrescentada ao atlas quando a definição aparece ou muda, sem reconstruir nada.

Ver Simulação e Desempenho (teste de 37 500 instâncias).

Exemplo

examples/macros-demo.bitwerk tem um contador de décadas a alimentar um driver BCD → 7 segmentos com sete LEDs, um somador de 4 bits com interruptores e LEDs e uma NAND quádrupla em DIL-14:

bitwerk examples/macros-demo.bitwerk --run --enter 3

Clone this wiki locally