Análise do manual de instalação anterior: o que ficou incorreto, o que precisa de ajuste e o que está faltando
Afirmações que eram verdadeiras quando a edição anterior saiu, mas que hoje levariam o leitor ao erro. No novo manual elas foram corrigidas ou marcadas como «era verdade antes» — as ilustrações foram mantidas, para que um leitor com uma versão antiga do software ainda reconheça as suas próprias janelas.
| Na edição anterior | Como é hoje | Seção do novo manual |
|---|---|---|
| «Intel Quartus Prime Lite», «Intel Altera», «FPGA da Intel Altera» — nos títulos e ao longo de todo o texto. | A divisão voltou a se chamar Altera: a Intel vendeu a participação de controle em 2024. Os lançamentos novos do Quartus Lite se instalam em altera_lite e o Quartus Pro em altera_pro (os antigos iam para intelFPGA_lite e intelFPGA_pro). Os scripts procuram todas as oito grafias. | 4.1.1, 4.1.1.4 |
«Acrescente as seguintes variáveis de ambiente ao arquivo ~/.bashrc»: QSYS_ROOTDIR, QUARTUS_ROOTDIR e um acréscimo ao PATH — apresentado como passo obrigatório. | O passo deixou de ser obrigatório: os scripts encontram o Quartus sozinhos, por QUARTUS_ROOTDIR, depois pelo PATH, depois pelos diretórios do fabricante em $HOME, /opt e /tools. As variáveis só são necessárias para uma instalação em lugar incomum ou para forçar uma entre várias versões. | 4.1.1.4, 4.2.1.4, 12 |
No mesmo exemplo, QUARTUS_ROOTDIR aponta para intelFPGA_lite/21.1, enquanto o PATH aponta para intelFPGA_lite/20.1. | Isso é um erro de digitação da própria edição anterior: os números de versão de linhas vizinhas não concordam, e um diretório inexistente entra no PATH. Como as variáveis já não são necessárias, o exemplo foi removido. | 4.2.1.1 |
| «Instalação do Icarus Verilog 12» — nos títulos das seções 1.6 e 2.4 da edição anterior. | É preciso a versão 13, de preferência a 14: alguns exemplos usam construções de SystemVerilog que as versões 11 e 12 não entendem. Os scripts verificam a versão e avisam. | 4.1.5, 4.2.5 |
Toda a seção 3 — instalação do OpenLane por Docker: git clone The-OpenROAD-Project/OpenLane, make, make test, make mount. | No basics-graphics-music o OpenLane foi substituído pelo LibreLane, sua continuação. Ele se instala pelo Nix, sem Docker, e se executa como ./07_synthesize_for_asic.bash do diretório do exemplo, e não como make do diretório do OpenLane. A seção foi reescrita por completo. | 4.1.11, 4.2.11 |
| «O OpenLane só pode ser instalado no Linux, portanto, se você usa Windows, instale um segundo sistema operacional ou uma máquina virtual». | No Windows o WSL 2 basta — não é preciso outra partição nem máquina virtual. Nix e LibreLane funcionam dentro do WSL, e esse é o caminho normal. | 4.1.11 |
O repositório de exercícios: git clone https://gitflic.ru/project/yuri-panchul/systemverilog-homework.git. | O endereço está obsoleto. Para as aulas da Escola, use github.com/chipdesignschool/systemverilog-homework. | 1.3, 9 |
O repositório de exemplos: git clone https://github.com/yuri-panchul/basics-graphics-music.git. | A cópia yuri-panchul é a de trabalho; nela entram alterações experimentais. A cópia destinada às aulas da Escola é github.com/chipdesignschool/basics-graphics-music, e a dos seminários internacionais é verilog-meetup. | 1.2 |
A menção ao repositório valid-ready-etc no gitflic (na parte sobre atualizar os repositórios do SSD). | Esse repositório está obsoleto; o seu material foi incorporado ao basics-graphics-music, na parte 4_microarchitecture. | 6.3 |
Caminhos de exemplo na forma labs/01_and_or_not_xor_de_morgan. | Os exemplos agora estão agrupados por parte do curso: labs/1_basics/1_01_and_or_not_xor_de_morgan, labs/2_graphics/… e assim por diante. | 6.4, 8.1 |
| FAQ: «Lista de placas suportadas … em setembro de 2024» — 39 placas. | Hoje são suportadas 54 placas (os 112 diretórios são as mesmas placas em configurações diferentes). A lista desta edição é lida diretamente do arquivo boards/README.csv do repositório, de modo que não pode divergir do código. | 3 |
| «Para instalar o Vivado ou o Gowin IDE você pode usar as informações disponíveis na internet» — ou seja, não há instruções. | Essas seções agora existem: instalação do Vivado e do Gowin EDA em todos os sistemas, drivers dos gravadores, regras udev e a explicação de como os scripts localizam cada uma dessas ferramentas. | 4.1.2, 4.1.3, 4.2.2, 4.2.3 |
| «Tudo é distribuído gratuitamente … cópias estão hospedadas no Yandex Disk» — com links de nuvem como forma principal de download. | Links para cópias em nuvem são efêmeros e envelhecem rápido dentro do texto de um manual. Esta edição indica as fontes oficiais e menciona as distribuições da própria Escola como alternativa, sem links específicos. | 4.1.1, 11 |
RARS: «será preciso pelo menos Java …», seguido da instalação manual do OpenJDK, do JAVA_HOME e de %JAVA_HOME\bin no PATH. | Em %JAVA_HOME\bin falta o sinal de porcentagem de fechamento — a grafia correta é %JAVA_HOME%\bin. No Linux, o Java se instala com o único comando sudo apt install default-jre e não exige variável alguma. | 4.1.9, 4.2.9 |
Aqui o texto antigo não está errado, mas incompleto: vale para um caso e silencia sobre os demais, ou dá uma instrução sem o motivo, deixando o leitor sem saber quando pode fugir dela.
| Na edição anterior | Como é hoje | Seção do novo manual |
|---|---|---|
| O Quartus é citado como «21.1 Lite», como se fosse a única versão. | A 21.1 Lite continua sendo a recomendada, mas precisa de ressalvas: placas com Cyclone II exigem o Quartus II 13.0sp1; com Cyclone III, a 13.1 (a 21.1 já não suporta essas famílias); e a DE23-Lite exige o Quartus Pro com licença gratuita. Os lançamentos recentes (24.1, 25.1) também servem para as placas atuais. | 3.1, 4.1.1 |
| «Deixe o caminho de instalação do programa no padrão». | O conselho é correto, mas vale explicar por que ele importa e quando se pode fugir dele: o caminho não deve conter espaços nem caracteres fora do alfabeto latino, e uma instalação em diretório incomum exige definir QUARTUS_ROOTDIR. | 4.1.1, 4.2.1.1 |
| Driver do USB Blaster: descrevem-se o USB Blaster e o USB Blaster II. | Falta o USB Blaster III — usado na DE23-Lite. No Linux, trata-se de uma linha adicional de regra udev com idProduct 6022; sem ela a placa não pode ser gravada. | 4.1.1.2, 4.2.1.2 |
| A regra udev é apresentada em um bloco único, sem explicação. | Ajuda explicar como o udev se comporta: todos os arquivos *.rules são lidos, na ordem dos nomes de arquivo, e o operador := proíbe qualquer alteração posterior do valor. Assim, o seu arquivo e o que vem com o Quartus não entram em conflito, mas vence o que vem primeiro na ordem alfabética. | 4.2.1.2 |
| VS Code: recomenda-se uma extensão, a SystemVerilog - Language Support. | Vale acrescentar o Surfer — uma extensão que mostra as formas de onda dentro do próprio editor, sem alternar para outro programa. | 4.1.6, 4.1.7 |
| O GTKWave é apresentado como o único visualizador de formas de onda. | Agora existe uma alternativa, o Surfer; ele é escolhido com WAVE_VIEWER=surfer e é mais conveniente no macOS, pois se instala como um executável comum. No Apple Silicon os scripts, na verdade, esperam o Surfer. | 4.1.7, 4.3 |
| Vivado: «a imagem do instalador passa de 80 GB», com a versão 2022.2 recomendada. | O tamanho depende das famílias de dispositivos escolhidas — selecionando apenas as necessárias, o download fica bem menor. Os scripts funcionam com qualquer versão de 2018 em diante e, a partir da 2024.2, entendem a nova disposição de diretórios (<pai>/<fabricante>/<versão>/Vivado em vez da anterior <pai>/<fabricante>/Vivado/<versão>). | 4.1.2 |
| SSD inicializável: «comece a pressionar uma das teclas para entrar no BIOS». | A tecla abre o menu de inicialização, e não o BIOS — são coisas diferentes, e em parte dos computadores as teclas são outras. Vale também explicar por que o script apaga a tabela GPT de reserva. | 6.1, 6.2 |
A máquina virtual de verificação: «a senha do usuário», sem dizer o login; a imagem do SSD usa verilog como login e senha, enquanto a máquina virtual de verificação usa a senha 1234. | Duas imagens diferentes, com credenciais diferentes, se confundem facilmente; por isso nesta edição as credenciais aparecem ao lado de cada imagem, separadamente. | 5, 6.2, 7 |
| Os passos 1.1 a 1.3 (Windows) e 2.1 a 2.3 (Linux) «podem ser pulados» se a placa não for Altera. | É verdade, mas é melhor dizer ao contrário: instale a ferramenta que corresponde à sua placa, e a tabela da seção 3 diz exatamente qual é. Sem placa, nenhuma ferramenta é necessária. | 3, 12 |
| «O manual pode ser atualizado; acompanhe as notícias no site e no canal do Telegram» — com o link do canal. | Vale acrescentar que o próprio repositório tem um diretório docs/ com arquivos separados sobre Quartus, Gowin EDA, Yosys, Vivado, WSL e QEMU — ele é atualizado junto com o código e por isso está sempre mais atual do que qualquer manual. | 11 |
Assuntos que simplesmente não existem na edição anterior. Alguns chegaram com ferramentas novas; outros já existiam, mas nunca foram escritos.
| Na edição anterior | Como é hoje | Seção do novo manual |
|---|---|---|
| Suporte a macOS. | A edição anterior cobre apenas Windows e Linux. No macOS não existe nem Quartus nem Vivado, de modo que placas Altera e Xilinx exigem máquina virtual; em contrapartida, Gowin EDA, OSS CAD Suite, Icarus, Surfer e LibreLane funcionam. Há particularidades próprias: Gowin EDA apenas em Apple Silicon, um pacote de aplicativo em vez de um diretório (Contents/Resources/Gowin_EDA), o atributo com.apple.quarantine e um visualizador de formas de onda que depende do processador. | 4.3 |
| OSS CAD Suite. | Um pacote único com Yosys, nextpnr, Icarus Verilog, GTKWave e as ferramentas de gravação. Cobre placas Lattice e Gowin sem ferramenta proprietária e fornece um Icarus recente onde a distribuição só traz um antigo. Basta descompactá-lo em ~/oss-cad-suite. | 4.1.4, 4.2.4 |
| Surfer — o programa e a extensão do VS Code. | Uma alternativa ao GTKWave para ver formas de onda. | 4.1.7 |
| XPACK RISC-V GCC. | O compilador de C e assembly para programas que rodam em núcleos de processador dentro do FPGA — inclusive no núcleo aps do MIET. Sem ele, as partes do curso sobre programar o seu próprio processador não podem ser feitas. | 4.1.10, 4.2.10 |
| Programas de terminal: minicom, picocom, putty. | Necessários para enviar um programa para a placa pela UART e conversar com o processador. No Linux é preciso ainda incluir o usuário no grupo dialout. | 4.2.10, 8.2 |
Escolha do núcleo RISC-V: aps (MIET), yrv, picorv32. | Alternado pelo script 13_choose_another_riscv_core_for_software.bash. | 8.1, 8.2 |
| Uma tabela de placas que informa a ferramenta e as versões aceitáveis. | Na edição anterior, a lista de placas do FAQ trazia apenas o nome e a família de FPGA. A nova tabela cobre 54 placas com o fabricante do FPGA e da placa, a família, a ferramenta necessária com a faixa de versões, se há TM1638 e como o vídeo está ligado. | 3 |
| A explicação de como os scripts encontram as ferramentas. | O motivo mais comum de mensagens no grupo de conversa é «o script não encontra o Quartus» ou «encontra a versão errada». Esta edição descreve a ordem de busca de Quartus, Vivado e Gowin EDA, junto com a regra de escolha da versão pelo chip da placa e o cache em ~/.cache/basics-graphics-music. | 4.1.1.4, 4.1.2, 4.1.3 |
| A lista dos scripts de um exemplo e a ordem de uso. | A edição anterior terminava na verificação da instalação e não explicava o que fazer depois. Agora os 14 scripts estão descritos, de 01_clean a 14_run_terminal_program. | 8.2 |
| De que o curso é feito: as partes basics, graphics, music, microarchitecture e cpu. | Um mapa do que está em cada parte e do que aparece na placa — para que fique claro para que serve todo esse software. | 8.1 |
| Uma seção própria sobre o systemverilog-homework. | Antes o repositório era citado em uma única linha, com endereço obsoleto. No entanto ele precisa apenas de Icarus Verilog e Git — nem placa nem ferramenta de fabricante —, o que o torna um bom ponto de partida antes de a placa chegar. | 1.3, 9 |
| Tiny Tapeout — fabricar um exemplo como um chip de verdade. | O modelo aproveita o módulo lab_top do exemplo, o mesmo que foi depurado na placa; a fabricação é feita na fábrica do IHP. A verificação local é ./07_synthesize_for_asic.bash. | 10 |
| O Icarus do OSS CAD Suite e a compilação a partir do código-fonte. | Duas formas adicionais de obter o Icarus 13 ou 14 quando os repositórios da distribuição só trazem a versão 11 ou 12. | 4.1.5, 4.2.5 |
| Um FAQ de instalação. | O FAQ anterior consistia em um único item, a lista de placas. O novo responde às perguntas que as pessoas realmente fazem: qual ferramenta instalar, se dá para trabalhar sem placa, se o PATH é necessário, por que nenhuma versão do Quartus serve, por que os scripts não rodam pelo cmd.exe e o que fazer com a quarentena do macOS. | 12 |
| A seleção da placa por um único script. | O ./check_setup_and_choose_fpga_board.bash verifica o software instalado e guarda a escolha da placa para todo o repositório — um passo que a edição anterior nunca descreveu, apesar de os exemplos não poderem ser compilados sem ele. | 6.4, 8.2 |
Três imprecisões no próprio enunciado e na lista de recomendações. Estão listadas em separado para que as correções não pareçam arbitrárias: o manual traz as formas corrigidas.
| Onde | O que se queria dizer |
|---|---|
| O enunciado desta edição, item 2: «13.0sp1 for Cyclone II boards and 13.1 for Cyclone II boards». | Na segunda vez, claramente queria-se dizer Cyclone III: a 13.0sp1 é a última versão com Cyclone II e a 13.1 a última com Cyclone III. O manual traz essa forma. |
| O enunciado, item 3: «novas placas suportadas, como a DE3-Lite». | A placa se chama DE23-Lite (Terasic, Agilex 3). Não existe placa chamada DE3-Lite; existem a antiga DE3, com Stratix III, e a DE10-Lite, com MAX 10. |
| O enunciado, roteiro da seção «O que há de novo»: «Mencionar a atualização para a DE23-Lite, Sound Blaster III». | O que se queria dizer é USB Blaster III — um gravador (idProduct 6022), e não uma placa de som. O item 6 da lista de recomendações diz o mesmo. |
As divergências foram encontradas comparando três fontes:
Инструкция_по_установке_ПО.pdf (68 páginas) — linha por
linha;main do repositório basics-graphics-music — os scripts
scripts/steps/00_setup_*.source_bash e os diretórios
boards/ e docs/. Onde o manual e o código discordam,
o código está certo: é ele que é executado;A tabela de placas da seção 3 do manual não foi redigitada à mão; ela é
gerada a partir do próprio boards/README.csv do repositório. Por
isso ela não pode divergir do código como divergiu a lista do FAQ antigo: para
atualizá-la, basta pegar aquele arquivo de novo.
A ordem de busca das ferramentas foi conferida não apenas lendo os scripts,
mas executando-os: a determinação da versão do Quartus a partir do chip da
placa foi feita com as consultas Tcl get_part_list e
get_family_list a cada versão instalada, confirmadas por sínteses
reais. Daí a regra: a compilação é possível se o chip está na lista de
dispositivos ou se a sua família está na lista de famílias —
nenhuma das consultas basta por si só.
As seções que não puderam ser verificadas em equipamento real estão marcadas como «não verificado» no manual. São o macOS e as datas e o custo dos shuttles do Tiny Tapeout.