требования к документации Опции

[Maverick]

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

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

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

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

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

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

[Doka]

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

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


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

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

[Maverick]

Maverick
дабы не придумывать велосипед и экономить время - можете рекомендовать смотреть 5ю главу RMM: RTL Coding Guidelines (параметры, выбор именования сигналов, написание "прозрачного кода", языковая переносимость, использование бибилиотек, реокмендации по схемам сброса и такта, деление проекта на модули)
а по поводу перечня файлов в комплекте поставки - это параграф 9.1.1 там же (в принципе справедлив и для ПЛИС): Soft Macro Deliverables.

Soft Macro Deliverables
RMM: RTL Coding Guidelines

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

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

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

[des00]

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. вы заказали разработку с покупкой кода и они ведут себя так, то сами виноваты. Спрашивайте манагеров почему подписали договор на таких условиях!!! Это по сути деньги выкинули в трубу, гарантий саппорта никаких, в случае смены платформы, модернизации почти полная переписка.

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

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

Удачи!!!

[Maverick]

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