Задача такая есть заказчик (в данном случае допустим я) и есть исполнитель (в лице другого предприятия). Исполнителю было поручено разработать цифровой блок на VHDL (исходные коды предоставил), но для более быстрого понимания работы написанного кода хотелось бы:

P.S. Это как я попытался сформулировать:

Требования к написанию программ и документации для ПЛИС

• Файл/документ, содержащий описание всех констант, переменных, сигналов.
• TEST BENCH файл/документ с описанием для возможности моделирования работы.
• Описание работы функциональной модели (схема, конечный автомат состояний (диаграмма состояний конечного автомата), и временная диаграмма работы (скриншоты с ModelSim).
• В исходном коде программы должны присутствовать комментарии, облегчающие понимание программы.
• Подробное описание всех входных и выходных сигналов с предъявляемыми к ним требованиями (например потенциальная или импульсная команда(ее длительность)).
• По возможности большую программу/схему разбивать на подпрограммы/подсхемы.
• На начальном уровне соединение всех функциональных блоков производить в Schematic Editor (например, Синхрогенератор <=> Модуль связи УПСОС-ПК) (может заменить функциональную/структурную схему).
• При использовании ядер из CoreGenerator описать процесс создания.
• При написании исходного кода программы максимально использовать механизм настраиваемых параметров Generic (например, для разрядности данных, адресов и т. д.).

Но мое начальство говорит, что лучше руководствоваться ГОСТами. Соответственно вопрос есть ли какой то ГОСТ на оформление документации (для программ для ПЛИС).

P.S. Прошу прощения, что может не в тему. Просто здесь чаще бывают люди которые с этим непосредственно связаны

Нашел ГОСТ, но он больше относится к программистам под Windows

Взят ГОСТ отсюда
http://doka.info/recommendations/gost

Врядли то, что было поручено исполнителю, можно назвать программным кодом. Это текстовое описание схемной реализации устройства. И вряд ли ее можно привязать к единой системе программной документации. Это файл прожига ПЗУ. К нему инструкция по прожигу.
Все остальное - за кружкой пива.

Например у Вас был узел на элементах средней степени интеграции. (Документация - Э3, ПЭ3).
Теперь это ПЛИС с загрузочным ПЗУ. С тем же набором документации + файл прожига ПЗУ.
Кому нужны приключения с программным кодом.

посмотрите у синопсиса (synopsys.com) как они оформляют свои IP (там может регистрироваться надо - смотреть designware, star ip),

понятно, что разработка IP (со всей "требухой") и просто написание кода сильно разные задачи, но пример "как принято"

из "свободного" кода считаю удачно (но слышал и другое мнение) сделано у gaisler.com - там VHDL код, набор утилит для сборки/симуляции, доки - не супер, но вполне - все бы субподрядчики так делали, жить было бы легче

С Вами полностью согласен! Хорошо, попытаемся абстрагироваться, если это цифровая схема (не важно как она сделана - описана на VHDL или нарисована в схематике, или распаяна на плате отдельными микросхемами цифровой логики), то к ней как к любой схеме должно идти хоть какое-то описание например: функциональная схема, циклограмма работы, описание входов/выходов и т.д. Для программ под Windows так делается!

Есть ЕСКД. Есть стандарты предприятия. Вы как заказчик сами определяете минимальный состав документации, например на узел. Ведь все денег стоит.
Что касается документации на сам проект. Даже не знаю. Если Вы заказчик IP core, наверно достаточно стандартного описания вне ЕСКД, чтобы использовать его в работе. Обьем такой документации - это наверно предмет трудового соглашения.

если не против, добавлю свои 5 капель



Если с константами и макросами синтеза еще нужно согласиться, то переменные и сигналы это бред
Временная диаграмма работы нужна только для внешних интерфейсов, для внутренних ИМХО пустая трата времени. Особенно если есть тестбенчи.



В подробном описании не вижу смысла, достаточно краткого описания интерфейса внутреннего модуля. Да и то если модуль тривиальный (мультиплексор, сумматор переносом и т.д.) или код самодокументированый то смысла в этом вообще нет.



ИМХО полный бред, владеть хдл и при этом рисовать ? И это при наличии функциональной схемы ?
Насчет ядер : завернуть ядро в обертку и описать что делает обертка. Этого достаточно.


ИМХО в свое описании вы упускаете цель разработки. Решите что вы покупаете : готовое ядро или разработку с кодом.

Если покупаете ядро, то все что касается его внутренностей вам не важно. Главное что бы работало и соответствовало ТЗ. (при этом разработчик вообще может пропустить код через обфускатор для сокрытия тайны). Примеры документации можете посмотреть в описании коммерческих/открытых IP

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

Но тут все зависит от условий :
1. если вы покупаете готовую разработку то насчет кода поезд уже ушел, можно требовать только
документацию ( и то скорее всего за создание дополнительной документации, нужно будет заплатить)

2. если вы заказываете разработку то тут :

ИМХО нужно в обязательном порядке оговорить соглашение об именах, правилах и принципах проектирования !!!

это позволит заранее оговорить вопросы



и заставить разработчика писать самодокументированый код.

Также требуется тщательная разработка и документирование функциональности и параметров модуля, утверждение плана и методов верификации с описанием тестовых случаев и coner case.

Ну ИМХО вот так в кратце.

Ну и дополнительное пожелание : все вносите на бумагу с подробным описанием. Иначе разрабочик легко отвертится (конечно в будущем ему с вами может быть и не работать, но в текущем бабло получит).

Поэтому не верьте записям в договоре вида "предоставить все документацию, которая использовалась для разработки." Вы думаете что сюда будут входить мини ad-hoc тестбенчи и другая документация об архитектуре подмодулей, а разработчик предоставит функциональную схему высокого уровня абстракции.

Также не рекомендую принимать работу в виде проектов CAD с визуализаторами (HdlDesigner) например. Во первых ваша фирма может не использовать данный софт, будут проблемы переносимости кода между разработчиками которые его не используют ну и по хорошему нужно его лицензировать.

Удачи !!!

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

Maverick
дабы не придумывать велосипед и экономить время - можете рекомендовать смотреть 5ю главу RMM: RTL Coding Guidelines (параметры, выбор именования сигналов, написание "прозрачного кода", языковая переносимость, использование бибилиотек, реокмендации по схемам сброса и такта, деление проекта на модули)

а по поводу перечня файлов в комплекте поставки - это параграф 9.1.1 там же (в принципе справедлив и для ПЛИС): Soft Macro Deliverables.


по поводу документирования алгоритмов: как минимум должна быть общая и помодульная функциональная схемы + структурная (RTL) там, где это необходимо (т.е. существуют особенности кодирования при реализации)

мне очень нравится подход Xilinx в описаниях к ЦОС-блокам CoreGen: datasheet - фактически статья-руководство по написанию соответствующего блока, с достаточно хорошим изложением теории работы, функциональными схемами и ссылками на необходимую литературу в конце документа.

Soft Macro Deliverables
RMM: RTL Coding Guidelines

А не могли бы Вы дать ссылку либо эти файл, плиз



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

Все правильно. Разработчики не любят предоставлять сопроводительную документацию, а особенно такую подробную, ведь в этом случае вы фактически берете их наработки, на которых они и живут. Был случай, когда одна контора отказалась от разработки, когда заказчик пожелал увидеть исходники всех используемых ими модулей. Они сказали так: на разработку библиотек мы потратили очень много времени, и их стоимость превышает ваш заказ десятикратно, либо повышайте соответственно стоимость гонорара, или идите "лесом". Может получится так, что внутренную документацию вам не предоставять ни за какие деньги, всегда оговариваете это на этапе ТЗ.

http://disk.tom.ru/qz6ff4b

на фтп лежит, но т.к. он лежит то попробуйте забрать с томского файлообменника




это стиль описания, когда большая часть функционала модуля/библиотеки понята без комментариев, банальным прочтением кода



так называемые naming convention и design rules это простые правила которых нужно придерживаться при создании кода. Примеры для ХДЛ есть на этом форуме, в сети, в книгах Ben Cohen, Janic Bergeron а и т.д. Если придерживаться этих правил тогда смена разработчика будет происходить менее болезненно.



обертка - wrapper, black-box. модуль созданный по принятым соглашениям, в котором ядро вставлено как под-модуль. Облегчает понимание, переход между архитектурами и т.д.




Еще раз повторюсь : если это ваши коллеги то тут поможет только начальство, но краткое руководство пользователя ИМХО быть должно.

Если это ваши аутсорсеры (суб-подрядчики) :
1. вы покупаете у них готовую разработку то полное руководство пользователя и пример использования IP (ad-hoc testbench) быть обязано!!! Спрашивайте манагеров почему купили IP с никакой поддержкой и документацией.

2. вы заказали разработку с покупкой кода и они ведут себя так, то сами виноваты. Спрашивайте манагеров почему подписали договор на таких условиях!!! Это по сути деньги выкинули в трубу, гарантий саппорта никаких, в случае смены платформы, модернизации почти полная переписка.

Рекомендации : с такими командами аутсорсеров не работать.

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

Удачи!!!

Всем спасибо за очень хорошие ответы

Поделитесь, плиз, данной литературой (книги Ben Cohen, Janic Bergeron и как делается обертка - wrapper, black-box), либо дать ссылку на сайты где могу почитать об этом

Soft Macro Deliverables
RMM: RTL Coding Guidelines
Подскажите где лежит эта книга на ФТП. не смог ее найти