Сравнение двух уроков про светофор

Вы дали Codex и мне одно и то же задание: файл 20261019_exercise.md, побайтно одинаковый в обоих каталогах. В нём нужен сайт breadboard/, первый урок которого — светофор на 4017 и элементах ИЛИ, в 15 разделах, на английском и русском. Здесь разобрано всё, что лежит в lssk_codex/breadboard, и сравнено с моим уроком breadboard/m11_traffic_light.

Один из двух сайтов написал я. Чтобы сравнение было честным:

Codex продолжал править файлы, пока я работал. README, страницы и заметки о Questa изменились в 13:21–13:22, а HDL не менялся с 07:30. Разбирается снимок, сделанный 21 октября в 13:27 PDT. В lssk_codex я ничего не менял.

Правила у нас были разные. Codex получил yuri_rules_3.txt с восемью правилами. Я получил yuri_rules_4.txt: в нём два из этих правил и фраза «Asynchronous reset is also OK». В разделе о стиле оба сайта проверены по всем правилам.

Оба проходятТри тестбенча Codex проходят в Icarus 12 и 14, Verilator и Questa (Questa я запускал сам, с лицензией)
Обычный Yosys: нетtimeunit в каждом RTL-файле: Yosys 0.69 read_verilog -sv падает на строке 15. Мой код синтезируется.
12/12 против 9/12Пойманные ошибки: три тестбенча Codex вместе против моего одного
19 × # 1, 2 × negedgeВ тестбенчах Codex. У меня нет ни того, ни другого: задержка есть только в генераторе такта.
45 против 34 проводовCodex: 37 перемычек, 2 провода питания и 6 проводов модулей. У меня: 24 перемычки и 10 проводов модулей.
12 против 5Упоминания Тимофея на странице урока, считая код

Итог

Что говорят инструменты

ПроверкаCodexМой урок
Icarus 12.0PASS: все три тестбенча, 285 проверок в основномPASS: 82 проверки
Icarus 14.0 develPASS: все триPASS
Verilator 5.053 так, как его запускает скриптPASS: все три, с --timing и без -Wall; скрипт отключает PINCONNECTEMPTY и DECLFILENAMEPASS с -Wall
Verilator -Wall в режиме lint
  • RTL: 4 × PINCONNECTEMPTY из-за пустых выводов () в traffic_light_chips.sv.
  • Тестбенчи: PROCASSINIT на logic clk = 1'b0; — именно на ту форму генератора такта, которую предписывает rules_3.
  • Также DECLFILENAME на project.v, UNUSEDPARAM на clk_mhz и 14 пустых выводов в tb_integrations.
Только предупреждения о стиле; ни одно из них не указывает на ошибку.		 0 предупреждений. Неиспользуемые выходы подключены к именованным цепям, а у двух строк lint_off есть комментарий.
Questa 2025.2 с лицензиейPASS: все три тестбенча, 0 ошибок и 0 предупреждений. Я запустил из своей оболочки run_questa.sh Codex в версии 13:21. На странице ученикам по-прежнему сказано, что запуск здесь невозможен. PASS: 0 ошибок, 0 предупреждений
Yosys 0.69 read_verilog -sv, как в маршруте синтеза BGMОшибка разбора: rtl/traffic_light.sv:15: ERROR: syntax error, unexpected TOK_TIME_SCALE. Yosys 0.43 выдаёт ту же ошибку. OK:
  • traffic_light: 23 ячейки, 5 триггеров.
  • traffic_light_chips: 26 ячеек, 5 триггеров.
  • Верхний модуль TT проходит check -assert.
Yosys 0.69 + SlangOK: обе реализации; верхний модуль TT — 81 ячейкаНе нужен
Проверка проводкиСтатические проверки:
  • ни одно отверстие не занято дважды, нет замыканий;
  • все функциональные выводы подключены, выводы NC свободны;
  • разорванные шины питания соединены.
Я вручную сверил все 37 перемычек с цоколёвками микросхем и ошибок не нашёл.		 Статические проверки:
  • ни одно отверстие не занято дважды, нет замыканий;
  • нет висящих входов, у каждой цепи один источник.
Кроме того, список проводов моделируется и должен дать RRRRYYGGGG.
Проверка ссылок178 локальных ссылок проверены его validate.py; я битых не нашёлСсылки и якоря в порядке

Ошибки и неверные утверждения на сайте Codex

Упорядочены по тому, насколько они помешали бы ученику или учителю. В столбце «Доказательство» — то, что я сегодня запускал или читал. Цитаты со страниц Codex взяты из его русской версии.

№ВажностьЧтоДоказательствоКак исправить
1высокая timeunit/timeprecision во всех 11 HDL-файлах, включая синтезируемые. Стандартный парсер Yosys не может разобрать project.v для TT, обе реализации, модели микросхем и обе обёртки BGM. Codex пишет: «Встроенный парсер локального Yosys 0.43 не принимает объявления timeunit». Самая новая версия Yosys на этой машине падает точно так же.
  • Yosys 0.69+24 и 0.43 оба сообщают unexpected TOK_TIME_SCALE.
  • scripts/steps/00_setup_yosys.source_bash в BGM вызывает read_verilog … -sv.
  • В BGM timeunit встречается только в файлах tb.sv.
  • В разделе про TT Codex сам признаёт, что для шаблона «перед синтезом этих исходников нужно сменить фронтенд».
 Оставить timeunit только в тестбенчах, как в BGM. Пример в самом правиле был тестбенчем.
2средняя На схеме 1 нет ни триггеров, ни логических элементов для состояния. На ней блок «Циклический автомат» с десятью состояниями, который питает три элемента ИЛИ. Задание требует «gates, flip-flop and other elements in generic fashion». Общая схема на RTL — кольцо из десяти триггеров, но ни на одном рисунке этого кольца нет. images/logic_ru.svg, подпись: «блок задаёт поведение, а не кодирование памяти» Нарисовать регистр: либо десять триггеров в кольце, либо, как у меня, пятиразрядный счётчик Джонсона из самой 4017 с дешифратором из десяти элементов.
3средняя Два ожидания спада названы необходимыми, хотя они не нужны. В руководстве по стилю сказано: «Проверка сброса только по posedge не доказывала бы это поведение».
  • На самом деле причина в схеме считывания самого Codex: @ (posedge clk); # 1. Сразу после положительного фронта схема, которая считает по спаду, уже показывает ожидаемое значение, поэтому тестбенчу и нужен блок с negedge, чтобы её поймать.
  • В тесте INHIBIT у 4017 вывод CLOCK — просто вход проверяемого устройства. Тестбенч может подавать его, как любой другой вход, по положительным фронтам своего собственного такта.
Файл need_to_deviate_from_style.html не создан. В validation.json записано "style_deviation_required": false.		 Охота за ошибками: если удалить блок с negedge, основной тестбенч Codex пропускает «счёт по спаду». Моя проверка по положительному фронту эту ошибку ловит. Проверять в always @ (posedge clk), как в BGM. Такая проверка видит значения только что закончившегося такта.
4средняя Тимофей упоминается слишком часто и как автор идеи.
  • На каждой странице урока он упомянут 12 раз: 6 раз в тексте и 6 раз в коде, один из них в строке раздела 14.
  • В коде есть tt_um_timofei_traffic_light и 1_11_timofei_traffic_light.
  • В обоих подвалах и в README написано «Идея светофора: Тимофей Никифоров».
Именно это вы поправляли у меня: та же схема была опубликована раньше, в 2014 году на SlideShare, как студенческий проект B.Tech.		 Видимый текст: заголовок вкладки, h1, оглавление, заголовок раздела 1, текст раздела 1, подвал. На странице со списком ещё 2 упоминания. Убрать упоминание в подвале и имя в названиях модулей и путях. Оставить одно фактическое упоминание того, где описана схема.
5ниже средней Статус Questa на странице неверен для этой машины. В разделе 11 сказано: «Здесь FlexNet не видит host ID, и Questa сообщает Invalid host». Это верно только внутри песочницы Codex. В README написано то же самое. Обновлённый run_questa.sh самого Codex, запущенный из обычной оболочки, проходит все три тестбенча Сообщить реальный результат или не писать о песочнице на страницах для учеников.
6ниже средней Урок расходится с собственным списком упражнений и наборами Codex. В exercises.html упражнение называется P11 и использует модуль светофора на 5 В (строка 64 листа LSSK). В уроке оно называется BB-FSM-01, и в нём три отдельных светодиода на 5 В (строки 46–48). В самой таблице про эти три светодиода сказано «not really needed». lssk_codex/exercises.html, запись P11 Взять номер из списка и его модуль светофора. Один провод GND модуля заменяет три перемычки катодов.
7низкая Модуль питания нарисован вне платы, с «двумя проводами питания» к LP01 и LM01. Деталь из строки 56 — модуль питания для макетной платы, который вставляется прямо в шины. Значит, два провода лишние, и картинка не совпадает с руководством «Как начать». Таблица деталей Codex, текст под схемой 3 и строка 56 в сохранённых им строках таблицы Вставить модуль в шины на краю платы.
8низкая Координаты на шинах вроде LP25 и RM08 выдуманы. На настоящих платах у шин нет номеров отверстий. Разрыв между отверстиями 25 и 26 — допущение, и текст это признаёт. Раздел 7 и jumpers.csv Указывать места на шинах по напечатанным номерам столбиков, как в моём списке проверки: «верхняя шина +, столбик 12».
9низкая Неверная причина отказа от `default_nettype none. В руководстве сказано: «Questa отвергает их неявные типы цепей». Порты без типа цепи обязан отвергать любой инструмент — для этого директива и нужна. Кроме того, project.v теряет `default_nettype none и заголовок с input wire из шаблона TT, который цитировался в задании. Руководство по стилю, §16, и integration/tinytapeout/project.v Сохранить заголовок шаблона TT в исходном виде.
10низкая Проверка в Verilator слабее, чем кажется. Скрипт запускает его без -Wall и отключает два предупреждения, а на странице написано только «Все три тестбенча проходят». См. «Что говорят инструменты» выше Подключать неиспользуемые выходы к именованным цепям и запускать с -Wall.

Спорные проектные решения

Стиль тестбенчей и HDL по вашим правилам

Правила с пометкой только rules_3 получил Codex, а я — нет. Я всё равно проверяю по ним и свой код, потому что вы, возможно, захотите применять их к обоим сайтам.

ПравилоCodexМой урок
Никаких задержек # без необходимости оба 19 мест с # 1: 9 в tb_cmos, 6 в tb_integrations, 4 в tb_traffic_light. Некоторые стоят в задачах, которые выполняются сотни раз. Только # 5 в генераторе такта
Никакого negedge без крайней нужды оба 2 места, оба можно убрать (пункт 3)Нет
Следовать примерам BGM оба Нет проверки в always @ (posedge clk), нет was_reset, нет final. Входы подаются блокирующими присваиваниями в середине такта; <= нет нигде. Проверка по положительному фронту, was_reset, итог в final. Входы подаются через <= после @ (posedge clk).
Отступления описывать в need_to_deviate_from_style.html оба Не создан. Исключения объяснены вместо этого в руководстве по стилю.Отступлений нет
Новый синтаксис времени SystemVerilog вместо `timescale только rules_3 Сделано, но в каждом файле, и это ломает синтез (пункт 1) Единица времени не задана вовсе, так что она зависит от симулятора: Verilator сообщает $finish at 445ps, а Icarus использует свою единицу по умолчанию. Исправляется добавлением timeunit только в tb.sv.
wire только в виде wire a = …; только rules_3 Соблюдено Не соблюдено в трёх местах:
  • wire [9:0] q, q_chips; для выходов проверяемых модулей в tb.sv — так же сделано и в тестбенче FIFO в BGM;
  • wire unused_4071_j; и подобные в traffic_light_chips.sv;
  • wire [9:0] q; в project.v.
Выравнивать = только rules_3В основномДа
Такт в отдельном always # (period / 2) только rules_3 Да. Verilator -Wall выдаёт на это PROCASSINIT. У такта свой блок initial … forever, как в примерах BGM, но не в этой точной форме.
Задачи без begin/end в духе Verilog-95 только rules_3ДаЗадач нет
Тайм-ауты в тактах только rules_3500, 500 и 200 тактов Сторожевого таймера нет. Длина прогона фиксирована, поэтому он не зависнет, но счётчик тактов обошёлся бы в три строки.

Руководство по стилю у Codex (22 правила, на английском и русском, с копиями в Markdown) — хорошая идея, и в нём записаны коммиты исходных репозиториев, на которые оно ссылается. Три его правила противоречат сказанному выше: §17 требует timeunit везде, §16 даёт неверную причину для default_nettype, а раздел «Почему остаются отдельные # 1 и negedge» называет ожидания спада необходимыми.

Охота за ошибками: одни и те же 12 ошибок в обоих проектах

Каждая ошибка вносилась в свежую копию, и копия запускалась в Icarus 12. «Поймана» значит, что тестбенч не напечатал PASS. Для Codex «основной без negedge» — это tb_traffic_light.sv с удалённым блоком проверки при низком уровне такта.

ОшибкаCodex
tb_cmos		Codex
основной		Codex
integrations		Codex основной
без negedge		Мой
Без ошибки (контроль)passpasspasspasspass
Общая схема считает по спаду тактапропущенапойманапропущенапропущенапоймана
Общая схема: синхронный сброспропущенапойманапойманапойманапоймана
Общая схема: сброс в состояние 1пропущенапойманапойманапойманапоймана
Общая схема: зелёный не горит в состоянии 6пропущенапойманапойманапойманапоймана
Микросхемы: вход ИЛИ красного на Q4 вместо Q3пропущенапойманапойманапойманапоймана
Микросхемы: вход ИЛИ зелёного оставлен на GNDпропущенапойманапойманапойманапоймана
Модель 4017: синхронный сброспойманапойманапойманапойманапоймана
Модель 4017 считает по спадупойманапойманапропущенапропущенапоймана
Модель 4017 игнорирует CLOCK INHIBITпойманапропущенапропущенапропущенапропущена
Модель 4017: CARRY равен 1 при счёте 0–5пойманапропущенапропущенапропущенапропущена
Элемент J в 4071 работает как И (жёлтый у Codex; у меня не используется)пойманапойманапойманапойманапропущена
Элемент K в 4071 работает как И (жёлтый у меня; у Codex не используется)пойманапропущенапропущенапропущенапоймана

Оформление и язык

Что удалось на сайте Codex

  • Чистая вёрстка: тёмная шапка с тремя числами (4/2/4, 3 микросхемы, 10 состояний), закреплённое оглавление и каждый раздел в своей карточке. Есть стили для печати.
  • Каждый рисунок — файл SVG со ссылками на SVG и PNG и с альтернативным текстом.
  • Обе страницы задают lang и hreflang, и языковые версии ссылаются друг на друга.
  • Семь аккуратных рисунков. На графе состояний выходы автомата Мура вписаны в вершины, а второй граф показывает унитарные коды. Цоколёвки понятны.
  • Таблица деталей ведёт на точную строку таблицы LSSK, например range=LSSK!A37:Q37, и к ней приложены файлы CSV с деталями и перемычками.
  • Небольшой пошаговый просмотр на JavaScript (пуск на 1 Гц, шаг, сброс) показывает десять состояний и огни. Он работает без сети.
  • Таблица неисправностей и задания «что попробовать дальше». Одно полезное замечание: в источнике «выходы 1–4, 5–6, 7–10» нумеруются с единицы, а в техническом описании — Q0–Q9.

Что не удалось

  • На страницах для учеников оказались заметки, предназначенные вам:
    • «в „hackaton_top“ из задания пропущена h» — это ещё и комментарий внутри hackathon_top.sv;
    • «Во время обновления Google-таблица не открывалась»;
    • «Требуемая цель совместимости — Icarus 13; именно эта версия здесь не установлена»;
    • история про host ID и FlexNet;
    • «загрузка завершилась тайм-аутом; технические выводы на неё не опираются»;
    • «использованы цитата из задания и сохранённый текст».
  • Рисунок макетной платы трудно читать. Десять сигнальных проводов выходят за плату и огибают её слева. Подписи закрывают номера строк и выводов, а модули такта и сброса не нарисованы. Чтобы собрать схему, ученику нужна таблица по отверстиям, а она свёрнута.
  • Временная диаграмма нарисована вручную, а не взята из моделирования. На ней нет сигнала сброса. Такт в момент t = 0 начинается с единицы, поэтому непонятно, какой фронт первым продвигает счёт.
  • У кода нет подсветки синтаксиса, и он свёрнут. Тёмной темы нет.
  • Называть статью на Habr «курсом Юрия Панчула» и помещать её под заголовком «Курс и упражнение со светофором» — расплывчато. Читателю помог бы номер урока, 1.7.

Русская страница

Перевод полный и раздел за разделом совпадает с английским. Проблемы — в терминологии и нескольких кальках:

Что перенять

Из урока Codex в мой

Я пока ничего не менял. Скажите, что из этого сделать.

  1. Модульный тестбенч для моделей микросхем в стиле posedge: все комбинации входов ИЛИ на всех выводах, а также CARRY и CLOCK INHIBIT у 4017. CLOCK INHIBIT можно проверить, подавая CLOCK как данные по такту тестбенча. Это закрывает три ошибки, которые я пропускаю.
  2. Моделирование обёрток (lab_top, hackathon_top, project.v) с обеими реализациями. Свои я ни разу не моделировал.
  3. Скрипт проверки синтеза: Yosys read_verilog -sv; synth; check -assert на стандартном парсере.
  4. Ссылки с деталей на строки таблицы LSSK, с сохранением моих цен.
  5. Файлы CSV с деталями и проводами и ZIP-архив упражнения без журналов сборки.
  6. Замечание о нумерации с единицы («выходы 1–4» — это Q0–Q3).
  7. Таблица неисправностей: для каждого признака — что проверить.
  8. Пункты rules_3, если вы хотите применить их и к моему коду:
    • timeunit 1ns; timeprecision 1ps; только в tb.sv;
    • logic для выходов проверяемых модулей и неиспользуемых цепей;
    • сторожевой таймер, считающий такты.
  9. По желанию: небольшой пошаговый просмотр состояний.

Из моего урока в урок Codex

  1. Схема 1 с настоящими триггерами и логическими элементами. Счётчик Джонсона с дешифратором — это и есть содержимое 4017.
  2. Рисунок макетной платы, похожий на настоящую плату, с модулями на ней, и список проверки с флажками.
  3. Временная диаграмма из VCD-файла моделирования, чтобы рисунок и тестбенч не могли разойтись.
  4. Проверка по положительному фронту с was_reset и final, которая убирает все задержки # 1 и ожидания спада.
  5. RTL, который принимает стандартный парсер Yosys, чтобы маршрут синтеза BGM и Tiny Tapeout работали без Slang.
  6. Модуль светофора из набора и цены из таблицы LSSK.
  7. Чистый прогон с -Wall, подсветка синтаксиса, кнопки копирования и тёмная тема.

Задание по пунктам

Пункт заданияCodexМой урок
1 · Номер, название, зачем это нужноBB-FSM-01 — новый номер, а не P11 из его собственного списка. Хорошая мотивация и предварительные требования.M11, номер из exercises.html
2 · Главный элемент, обозначения, таблица истинности, временная диаграммаГраф автомата, таблицы истинности ИЛИ, временная диаграмма от руки, пошаговый просмотрОбъяснение 4017 и временная диаграмма из моделирования
3 · ДеталиСтроки таблицы LSSK с прямыми ссылками и CSV; без цен; три отдельных светодиода; 37 + 2 + 6 проводовЦены и поставщики; модуль светофора; 24 + 10 проводов; без CSV
4 · Микросхемы, выводы, полярностьТри таблицы выводов и рисунок цоколёвок. Подробность про CLOCK INHIBIT со ссылкой на Nexperia.Цоколёвка и таблица для каждой микросхемы
5 · Схема 1: триггеры и логические элементыЧёрный ящик и три ИЛИ5 триггеров, 10 элементов И и 3 ИЛИ
6 · Схема 2: соединения микросхемАккуратная блок-схема на уровне выводовСхема на уровне микросхем
7 · Схема 3: макетная платаКарта отверстий со всеми 37 перемычками; плотная и абстрактная; CSV и таблица точныеРисунок платы с модулями, шаги сборки и список проверки с флажками
8 · Общая схема на SystemVerilogКольцо из десяти триггеров с унитарным кодомСчётчик Джонсона с дешифратором, как на схеме 1 и в 4017
9 · Модели микросхемПорты названы по выводам (p14_clock); помечены как синтезируемыеИмена из технического описания, номер вывода в комментарии; помечены как синтезируемые
10 · SystemVerilog: схема из микросхемСгенерирована из базы выводов и цепейСгенерирована из проверенного списка проводов
11 · Тестбенч для Icarus, Questa и VerilatorТри тестбенча; скрипты берут пути к инструментам из переменных окружения. На странице сказано, что Questa не запускается, хотя она запускается.Один тестбенч, три скрипта запуска и скрипт очистки; все три симулятора работают
12 · lab_top в BGMПолный интерфейс, светодиоды и цвет на LCD, сброс на key[0], скрипт размещения в BGMСветодиоды показывают бегущее состояние, семисегментный индикатор — огонь
13 · hackathon_top в BGMЗаливает LCD текущим цветомРисует светофор на LCD
14 · project.v для Tiny TapeoutИспользует clock_hz: 1 без делителя. DIP-переключатель выбирает полоски или цифру состояния, огни выведены ещё и на uio. Для синтеза нужен Slang.Использует clock_hz: 1 без делителя. Полоски на индикаторе; работает со стандартным Yosys; в комментарии сказано переименовать модуль.
15 · ПрочееШаги первого запуска, таблица неисправностей, задания «что попробовать дальше» и источникиЗадания, включая разрешение такта, и родственные схемы
Сайт: страница со списком, английская и русская версии со ссылками друг на другаДа, плюс руководство по стилюДа

Как проверялось