[arhiv6 20]

Добрый день. Интересует, как делается документация для современных микроконтроллеров (МК), чтобы применить подобный опыт в своей работе. Вопрос можно разделить на пару частей:

 

1) Как обеспечивается связка описания регистров между RTL-дизайном (какие-нибудь verilog файлы у разработчиков МК) /  SDK (заголовочные файлы для Си) / документацией (красивые таблицы с адресами регистров и их описанием в даташите)? Это же не вручную всё делается - есть какой-то исходный формат (какой?) описания регистров, из которого генерируется всё остальное. Вроде даже гугл выдал ссылки на подобный софт (rggen, corsair, hdl_registers, opentitan register_tool), пока изучаю. Разработчики МК используют что-то подобное? Как это хочу применить у себя: хочу упростить работу с написанием кода и документации в всоих проектах. Сейчас документация пишется в ворде, регистры описываются обычными таблицами. Потом приходится вручную по ним создавать заголовочные файлы для СИ (+ программисты FPGA по ним пишут свои верилоговские фалы). А т.к. идёт процесс разработки, всем участникам процесса приходится постоянно следить, чтобы у всех были актуальные и валидные данные о регистрах (адреса, размеры, наименования, описания и т.д.).

 

2) В любом случае, софт из предыдущего пункта не генерирует готовый даташит в pdf формате. На выходе получается какой-нибудь markdown или asciidoc файл, который содержит только описания регистров. Для получения полноценного Reference Manual его нужно "собрать" с остальной текстовой документацией (с описанием алгоритмов), вставить туда картинки, добавить перекрёстных ссылок и содержание, и только потом генерировать pdf. Как такое делается? Какие форматы используются для написания текстовой части документации? Какое ПО собирает всё вместе?  Как это хочу применить у себя: в идеале хотелось бы уйти от ворда. Он был выбран по причине низкого порога вхождения и возможности совместить в одном документе как текстового описания с картинками, так и таблиц с описаниями регистров. Но в итоге всё равно исходники картинок (visio файлы) приходится хранить в системе контроля версий рядом с вордовским документом. Внесённые правки в этот документ нормально не посмотреть, что усложняет командную работу. Но если уходить с ворда - то куда?

 

[Avex 1]

По собственному опыту могу сказать, что очень важно сначала писать документацию, а потом писать код на RTL (но не наоборот). При проработке документации полезно рисовать иллюстрации - не просто блок-схемы, а принципиальные схемы отдельных узлов. Примеры можно брать у TI и Infineon. Руководства по программной модели и описания регистров лучше выносить в отдельный документ, тут за образец хорошо брать ARM.
Когда есть документация, писать RTL на много проще: можно брать куски текста из описания и копипастить их в качестве комментария прямо в код. И думается и пишется легче.

По софту, я бы выбрал либреоффис  -там исключительная рисовалка картинок (Draw), а Write процентов на 90 совестим с вордом. И pdf выплевывает по одному щелчку. Другая альтернатива - эппловский оффис, но мне он вообще не зашел, хотя рисовалка там лучше визио, но хуже Draw

[Immortal_Buka 0]

1) https://en.wikipedia.org/wiki/IP-XACT ?

2) TeX - кмк, самый удобный вариант

Изменено 23 декабря, 2022 пользователем Immortal_Buka

[Plain 228]

Процесс называется вёрстка, её обычно делают в InDesign, и на TeX тоже можно, но дольше, по-моему, если нет особых нужд в виде правильно выглядящих формул и т.п., а PDF правильнее делать через PostScript и далее Acrobat Distiller — обе так умеют, но вроде могут и напрямую.

[tonyk_av 45]

15 hours ago, Plain said:

PDF правильнее делать через PostScript

Давно существуют и успешно используются конвертеры из ТеХ в PDF без промежуточных форматов.

Для ТеХ давно существуют графические фронтэнды типа WYSWYM, а не WYSWYG, поэтому получать аккуратную документацию относительно несложно.

[Plain 228]

Автор ищет средства автоматизации этапов вёрстки, я бы тоже от них не отказался, но по опыту, гораздо больше времени требуется для написания простого и понятного собственно текста.

[tonyk_av 45]

Ну так подберите подходящий шаблон и используйте его.

А если ещё и LyX под этот шаблон подточите, то, ИМХО, удобную среду для написания документации. ТеХ для тех, кто хочет думать что писать, а не как это размещать на странице.

Замечу, что в пределах ГРСТ 2.105 получаются вполне красивые документы.

[Plain 228]

17 минут назад, tonyk_av сказал:

получаются вполне красивые документы

Увидел кучу ошибок и не увидел красоты, второе субъективно. Ну и на TeX когда-то сверстал пару руководств пользователя, проблем не было.

[tonyk_av 45]

44 minutes ago, Plain said:

кучу ошибок

Да ну!

[Yra 4]

Я  приспособился делать следующее: В Verilog - коде/файлах проекта (да в любом другом коде, где есть многострочные комментарии) добавляю

такое:

/*

_latex_start_

\section{Описание того что считаю нужным описать }

текст, списки, таблицы, листинги, даже рисунки в tikz - формате, даже временные диаграммы в tikz - формате

_latex_end_

*/

Получается что - то вроде самодокументирующегося кода, только не для Doxygen а напрямую для Latex

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

https://github.com/yrasik/VP_auto/blob/master/bin/lua/get_latex_info_from_code.lua - он ни о чем, можно подобное на python изобразить - неважно. Этот скриптик извлекает всё что между тегами в комментариях в одноименные *.tex - файлы.

Эти файлы подключены к *.tex - файлу верхнего уровня.

Собираю всё это lualatex (из пакета TeXLive). Стилевые файлы и пр. можно отсюда https://github.com/yrasik/eskdi. Тогда можно умудриться по ЕСКД - описание оформить..

Незатейливые рисунки - блоксхемы можно приноровиться делать в  https://github.com/yrasik/tikzit (tikzit, наученный русским буквам) - главное преимущество этого изложено в https://github.com/yrasik/eskdi/blob/master/about.pdf в приложении Д.4. 

 

.. в общем надо переходить на Тёмную Сторону Силы...