Command Line Interface Guidelines

https://clig.dev

Шикарный гайд о том как организовывать CLI для своих программ. Начинается с общих рассуждений, и дальше покрывает все основные аспекты с примерами и ссылками на дополнительные ресурсы.

Минутка саморефлексии. Я очень люблю автоматизировать и писать прикладные инструменты/скрипты. Иногда даже больше чем решать непосредственно задачу с помощью этих инструментов.
И 9/10 из таких тулов обладают CLI. И это было непросто узнавать как правильно и удобно его организовывать. Всё методом проб и ошибок, гугления, чтения StackOverflow и подсмотра "как у взрослых сделано". Очень не хватало подобного единого гайда или чеклиста с лучшими практиками. Сейчас, конечно, многое из того что там очевидно, но всё равно находятся интересные места.
Не пожалейте полчаса на прочтение.

#cli #guide
@positiveslack

Рандомизация в Verilator

Тут оказывается у верилятора сподвижки в рандомизации случились.

Если сжать всю историю до нескольких предложений, то

▫️ Первым заходом в рандомизацию было использование API-вызовов библиотеки CRAVE. Решение как оказалось было не совсем подходящим - слишком громоздкий и универсальный инструмент, который сильно усложняет сборку самого верилятора.
▫️Далее пошел заход через SMT-LIB2 - SV констрейны конвертируются в Lisp-подобное описание, которое идёт в рантайме на вход любому (почти) из популярных SMT-решателей, установленных в системе. Далее остается лишь забрать выхлоп и разложить по переменным.

Именно последний подход начали пиарить в недавних статье и докладе про текущие дела верилятора. Хотя PR на Github находился еще в работе, да и судя по комментариям мистер Снайдер похоже не сильно был воодушевлен таким подходом.

Однако, работу довели до мержа в мастер, и теперь по умолчанию верилятор пытается использовать z3, как бэкэнд для рандомизации.

Рандомизация работает, я проверил. Однако надо убедиться что решатель есть в системе, иначе в рантайме будет сюрприз

%Warning: Subprocess command `z3 --in' failed: exit status 127

Но сама рандомизация пока еще довольно слабая - можно глянуть в оригинальном PR, что ограничений пока довольно много.

#verilator
@positiveslack

Кодер/декодер JSON на SV

ШОК!!! Программисты скрывали этот формат от верификаторов годами! Нужен всего лишь...

Короче говоря, я решил что существует недостаточно полноценных JSON кодеров/декодеров на SystemVerilog.

Почему JSON? Потому что он достаточно простой и хорошо формализированный чтобы его несложно было грузить и дампить, поддерживаемый всюду, а также всё ещё человекочитаемый. В общем, идеальный "великий уравнитель" если вдруг мы хотим гонять через IO данные, конфигурации, метрики, трассы, транзакции и прочее между симуляцией и внешним миром.

И вот он github репо. Без UVM, DPI и внешних зависимостей - на чистом SV. Практически полная поддержка спецификации (юникод не стал полноценно поддерживать, уж простите). И даже немного больше - есть некоторые SV-специфичные фичи.

Можно читать json, можно дампить, можно инспектировать, изменять и создавать дерево объектов руками. Можно даже имплементировать специальный интерфейс-класс в своём любом классе, и получить возможность дампа этого класса в json. Есть прозрачный механизм сигнализации об ошибках декодирования. В общем все то, что можно встретить на нормальных языках.

Для тестирования и разработки использовал SVUnit и Verilator. Тесты как свои, так и с использованием внешнего набора JSONTestSuite. Отмечу, что ни на одном коммерческом симуляторе пока не запускал, а с учётом того, что верилятор позволяет некоторые вольности, то высока вероятность что не заработает из коробки.

Документация доступна на сайте.

https://github.com/esynr3z/svjson

#system_verilog #json
@positiveslack

Кодер/декодер JSON на SV [1]

Ну и чтобы два раза не вставать, немного об инфраструктуре этого проекта.

По поводу симуляции и тестирования. Работать с верилятором не то чтобы просто - часто вместо дебага своей логики ты дебажишь верилятор. В итоге, в вериляторе было заведено дюжина багов (большинство пофикшено), и даже починена его совместимость с SVUnit, как я писал выше. В итоге, почти пятая часть ченджлога для 5.024 зарепорчена мной. "It ain't much, but it's honest work".
В любом случае, вдумайтесь - верилятор уже сносно работает с довольно абстрактным ООП кодом!

По поводу документации. Я очень люблю asciidoc, и с самого начала искал способы как бы поднять github pages на нём. Благо нашёлся проект Antora, причём похоже единственный в своём роде. Все остальные генераторы сайтов и документации, либо не поддерживают asciidoc, либо поддерживают через дополнительные плагины и телодвижения. Правда стандартный UI Antora имеет некоторые недостатки (например, нет подсветки SV в документации), но всё поправимо.

По поводу линтов и форматирования. Самое слабое место, т.к. ничего почти не настроено. Основной план - использовать максимально строгую компиляцию разных симуляторов как линты. Дополнительно можно попробовать что-то из отдельных линтеров прикрутить. Всё собирался в который раз попробывать форматтер Verible. Но раньше он всё время крашился на нетривиальном ООП коде.

По поводу автоматизации. Всё описанное выше положено на "бумагу" в виде Github Actions и просто делает "вжух" по новым PR и пушам в мастер. Да кстати, там кроме верилятора я поднял и модельсим (версия от альтеры) - это единственный коммерческий симулятор, который можно скачать по прямой ссылке и запускать без отдельной лицензии.

В итоге, надо еще немного дожать, и будет по инфраструктуре почти то, что доступно в больших ЯП из коробки и никаких трудностей не вызывает.

Ну и да, как бы то ни было, положительный сайд-эффект в виде ставших чуть лучше опенсорсных тулов уже оправдывает всю затею на 100%.

https://github.com/esynr3z/svjson

#system_verilog #json
@positiveslack

SystemVerilog Fork Disable Gotchas

Статья не очень свежая, но в ней удачно подсвечены основные примеры "неожиданностей" связанные с disable и fork.

Как отметил в комментах Дейв, стек вызовов и отношения parent-child у процессов связанные, но всё же ортогональные концепции. И если это держать в голове, то все уже и не так "неожиданно". Но на практике часто от этого не легче, поэтому в некоторых стайлгайдах манипуляции с disable запрещены совсем (поддерживаю).

TL;DR

◽️ disable <label> может убивать процессы во всех инстансах класса разом
◽️ disable fork убивает все дочерние процессы, даже если они форкнулись раньше внутри некоторого стека вызовов вне текущего таска
◽️ disable fork может убивать даже процессы, которые созданы после него, если будет задействован внешний цикл

Звучит громоздко, но лучше посмотреть примеры кода в статье вместо тысячи слов.

"Кто виноват" понятно, теперь "что делать":

◽️оборачивать куски с disable в дополнительный внешний fork-join, чтобы ограничить его "область видимости" за счёт нового родительского процесса
◽️не использовать disable, а использовать управление процессами через стандартный класс process и его API

🏆 В фонд цитат и выражений:

... or else it's, "Gotcha!!!" (I can almost picture the SystemVerilog language designers saying that out loud, with maniacal expressions on their faces).

#system_verilog #tldr #gotcha
@positiveslack

gradle-hdvl

https://github.com/tudortimi/gradle-hdvl

FYI, тут Тюдор Тими (который автор svunit и verification gentelman) поделился в ответ на оригинальный пост, что они в компании оказывается успешно юзают в проде Gradle для схожих целей и хорошо о нём отзывается:

We use it productively. The cool thing about Gradle is that it's very extensible and we built a few more proprietary plugins around it to customize it even further. I looked around at other tools before choosing it (like Bazel, CMake, I think also Conan, etc.), but Gradle had he best fit.

Так что если вдруг в компании есть скучающий джавист, то берите на заметку.

#java #automation
@positiveslack

Писать VIPы весело

"А давайте напишем универсальный VIP, который будет работать во всех основных симуляторах"

◽️Делаем красивые и подробные сообщения. Что напечатает код?

initial begin
    $display({"Hello", "from %s!"}, "testbench");
end

Правильно:
- одна половина симуляторов: Hello from testbench!
- другая: Hello from %s!testbench

◽️Пытаемся писать lint-free код.
Используешь $sampled в сообщении SVA - плохо, не используешь - тоже. Да что тебе надо то? Пример для VCS здесь.

◽️Хм? Сколько раз будет напечатано сообщение?

int unsigned num = '1;
repeat (num) begin
    $display("Hello!");
end

В Xcelium например ни одного, т.к. num скастуется внутри к int и получится отрицательное число для которого repeat не положены. И это будет отличаться от брата VCS, где честно будет напечатно всё.

И это только мелочи из недавнего. Есть примеры? Накидывайте.

#verification #vip #eda
@positiveslack

Next Level Testbenches: Design Patterns in SystemVerilog and UVM
By Mark Glasser

Тут недавно новая книга вышла, о которой мне лента линкедина любезно рассказала раз десять кряду.

Выглядит довольно интересно. Тема паттернов/шаблонов проектирования в SV ООП в интернетах представлена слабо, но является важной на мой взгляд. Т.к. верификация - это по сути написание программ, пускай и специфичных, а поэтому верификатор - программист, которому неплохо было бы знать и классические типовые подходы решения типовых проблем.

Я даже начал собирать информацию по теме, и писать некоторое количество заметок, в надежде сделать лонгриды, но теперь как будто уже не надо, т.к. там информации уже в разы больше.

Попадёт ли эта книга в must-read список верификатора? Кто знает. Осталось лишь дождаться пока приедет. Пока можно лишь изучить примеры из книги, лежащие на гитхабе
https://github.com/mxg/topaz

#system_verilog #book
@positiveslack

Astral: Next-gen Python tooling

Давеча изучал современный ландшафт тулов для питона, и чёт впечатлился ребятами из astral.sh. Они с ноги влетели в питон-сообщество, сказали что это вы тут за говно зоопарк тулов развели, вот у нас в расте есть единый Cargo и всё из коробки, сейчас мы вам нормальный тулчейн на расте напишем, и всё летать будет.
Да-да, это гремучая смесь из XKCD#927 и "Rewrite it in Rust" мема.

И самое главное - написали, да так, что за относительно короткий срок пошло терраформирование всего ландшафта, и крупные проекты начали переползать на их линтер-форматтер Ruff. Не говоря уже о мелких, где Ruff теперь считается стандартным выбором. Он покрывает целую пачку аналогов и работает реально быстро (в десятки раз быстрее, если точнее).

В этом году они выкатили UV - инструмент для закрытия другой нужды: менеджмента проекта, зависимостей, окружений и самих питонов. Один тул, чтобы покрыть pip, pipx, poetry, virtualenv и дальше по списку. Они там поглотили в процессе популярный rye, который преследовал похожие цели, и теперь декларируют uv как наследника. Инструмент тоже хайпанул и проходит стадию принятия сейчас.

Ну им осталось сделать лишь blazingly fast (c) тайп-чекер. И всё, дефолтный тулчейн будет готов. Поживем-увидим, выстрелят ли эти ожидания.

P.S. Про КДПВ. Звёзды гитхаба конечно так себе метрика, но на самом деле сейчас они там уже ушли в отрыв - 32k звёзд для ruff, что похоже больше чем у любого другого инструмента для питона.

#python #tool
@positiveslack

Про мажорные версии

Один реддитор спрашивает про питоний pydantic: "Как же так, библиотека переходит на новую мажорную версию, и теперь оказывается все туториалы устарели, а ChatGPT ещё не знает о новой версии. Что же делать? Как же жить?"

И разработчики такие, которые написали и поддерживают одну из лучших документаций среди питоньих либ, написали миграционный гайд, и всячески пытались "подстелить соломку" для бампа мажорной версии: "Ну да, ну да, пошли мы нахер". Т.е. вариант просто читать документацию как-то не рассматривается в принципе.

И это не первый пост на схожую тему на моей памяти. И всё чаще упоминается ChatGPT при этом всем. Похоже умение вдумчиво читать документацию переходит в разряд элитарных навыков?

И ведь в самом бампе мажорной версии нет ничего такого - это здоровый процесс развития, когда учитываются набитые шишки и дропается легаси.

Сейчас правда он сакрализирован настолько, что разработчики панически боятся бампать мажорную версию. Люди готовы или наслаивать хаки поверх устаревшей архитектуры, либо, что ещё хуже, ломать минорные версии и искать оправдания этому. И всё это подрывает саму идею semver и контракт с юзером о семантике изменений.

Есть даже пост от автора semver на эту тему: Major Version Numbers are Not Sacred. Там кроме всего, ещё и пояснения к тому, что мажорные версии никогда не должны были быть частью маркетинга и обязаны меняться так часто, как требует этого разработка. Рекомендую ознакомиться.

А вообще, можно ведь не мучить ни себя ни юзера ложными ожиданиям, и выбрать альтернативную схему версионирования, чтобы следовать ей до конца. Вон в TeX версия - это число, ассимптотически приближающееся к пи, а бамп - это добавление нового знака после запятой. Это хотя бы красиво.

#dev
@positiveslack

Дедлайновое

#meme
@positiveslack

Когда нет контента, но кладовая с мемами ещё не пуста

#meme
@positiveslack

Препроцессор SV как инструмент

Кстати, в процессе изучения sv-bugpoint узнал как можно свести проект любой сложности и структуры к одному SV файлу, т.к. инструменту на вход требовался строго один файл.

Просто прогнать все исходники/файллисты через препроцессор верилятора:

verilator -E -P [flags, sources] > output.sv

В stdout и получим желаемый файл. Супер просто и примитивно, но признаюсь, не знал что так можно.

Ещё один инструмент для исследования и диагностики в копилку.

P.s. если у кого-то нет верилятора, но есть квеста, vlog -mfcu -E делает то же самое.

#verilator #tips_and_tricks
@positiveslack

Автоматизация вокруг HDL

Ландшафт инструментов сборки, автоматизации и менеджмента HDL проектов очень неравномерный. Причем большая его часть скрыта "под землёй" во внутренних репозиториях компаний, где инструменты и скрипты разрабатываются с нуля внутри под конкретные нужды, боли и инфраструктуру компании.

Ниже я попробовал собрать в кучу то, что можно найти в открытом доступе. Классификацию тут проводить непросто, т.к. какие-то проекты пытаются быть всем, какие-то решить лишь один аспект, какие-то нацелены на FPGA, иные не имеют таких ограничений, и т.д.

Тем не менее, хотелось бы попробовать провести сравнительный анализ в будущем, поэтому если вдруг у вас есть опыт использования чего-либо ниже (или может чего-то, что я забыл), то поделитесь болью или успехом в комментах.

▫️orbit: Package manager and build tool for HDLs [Rust]

▫️bender: A dependency management tool for hardware projects [Rust]

▫️FuseSoC: Package manager and build abstraction tool for FPGA/ASIC development [Python]

▫️Edalize: An abstraction library for interfacing EDA tools [Python]

▫️Hdlmake: Tool for generating multi-purpose makefiles for FPGA projects [Python]

▫️Hog: Hog (HDL-on-git) is a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a git repository [Tcl, Shell]

▫️SiliconCompiler: Modular hardware build system [Python]

▫️Blockwork: An opinionated build environment for EDA projects [Python]

▫️HBS: Build system for hardware description projects, which was created out of frustration with all existing build systems for hardware description [Tcl]

▫️DUH: Suite of tools for packaging reusable hardware components and designs [JavaScript]

▫️Xeda: Cross-platform, cross-EDA, cross-target simulation and synthesis automation platform [Python]

▫️EDA²: Conceptual model for characterising the abstraction layers in Electronic Design Automation projects based on Hardware Description Languages [Python]

▫️LiteX:The LiteX framework provides a convenient and efficient infrastructure to create FPGA Cores/SoCs, to explore various digital design architectures and create full FPGA based systems [Python]

▫️DVSim: An industry-grade EDA tool flow manager / build and run system that strives to achieve a bug-free Silicon [Python]

▫️Hammer: Hammer is a physical design framework that wraps around vendor specific technologies and tools to provide a single API to create ASICs [Python]

#tool
@positiveslack

Забавное в UVM

Обнаружил что в UVM есть класс uvm_spell_chkr, который на самом деле то, что в названии. Начал смотреть зачем нужна проверка правописания? Может чтобы позволять работу с бд, даже при опечатках?

И почти угадал. Оказывается, что всё буквально ради сообщения при работе с resource pool, когда ты опечатался и ресурс не был найден:

"%s not located, did you mean %s"

Т.е. кто-то заморочился же с расстоянием Левенштейна и логикой вокруг на SV ради этого.

Не могу объяснить это чем-то кроме как: "Эй, Стасян, смотри чё могу. Круто же?"

#uvm
@positiveslack

Кокотбшное

Пожалуйста обратитесь за помощью, если у вас возникло желание так форматировать код

#meme
@positivelsack