|
|
  |
требования к документации |
|
|
|
Jun 4 2008, 12:10
|

я только учусь...
     
Группа: Модераторы
Сообщений: 3 447
Регистрация: 29-01-07
Из: Украина
Пользователь №: 24 839

|
Задача такая есть заказчик (в данном случае допустим я) и есть исполнитель (в лице другого предприятия). Исполнителю было поручено разработать цифровой блок на VHDL (исходные коды предоставил), но для более быстрого понимания работы написанного кода хотелось бы:
P.S. Это как я попытался сформулировать:
Требования к написанию программ и документации для ПЛИС
• Файл/документ, содержащий описание всех констант, переменных, сигналов. • TEST BENCH файл/документ с описанием для возможности моделирования работы. • Описание работы функциональной модели (схема, конечный автомат состояний (диаграмма состояний конечного автомата), и временная диаграмма работы (скриншоты с ModelSim). • В исходном коде программы должны присутствовать комментарии, облегчающие понимание программы. • Подробное описание всех входных и выходных сигналов с предъявляемыми к ним требованиями (например потенциальная или импульсная команда(ее длительность)). • По возможности большую программу/схему разбивать на подпрограммы/подсхемы. • На начальном уровне соединение всех функциональных блоков производить в Schematic Editor (например, Синхрогенератор <=> Модуль связи УПСОС-ПК) (может заменить функциональную/структурную схему). • При использовании ядер из CoreGenerator описать процесс создания. • При написании исходного кода программы максимально использовать механизм настраиваемых параметров Generic (например, для разрядности данных, адресов и т. д.).
Но мое начальство говорит, что лучше руководствоваться ГОСТами. Соответственно вопрос есть ли какой то ГОСТ на оформление документации (для программ для ПЛИС).
P.S. Прошу прощения, что может не в тему. Просто здесь чаще бывают люди которые с этим непосредственно связаны
--------------------
If it doesn't work in simulation, it won't work on the board.
"Ты живешь в своих поступках, а не в теле. Ты — это твои действия, и нет другого тебя" Антуан де Сент-Экзюпери повесть "Маленький принц"
|
|
|
|
|
Jun 5 2008, 10:52
|
Гуру
     
Группа: Свой
Сообщений: 2 435
Регистрация: 6-10-04
Из: Петербург
Пользователь №: 804

|
Цитата(Maverick @ Jun 4 2008, 16:10)  Задача такая есть заказчик (в данном случае допустим я) и есть исполнитель (в лице другого предприятия). Исполнителю было поручено разработать цифровой блок на VHDL (исходные коды предоставил), но для более быстрого понимания работы написанного кода хотелось бы: Врядли то, что было поручено исполнителю, можно назвать программным кодом. Это текстовое описание схемной реализации устройства. И вряд ли ее можно привязать к единой системе программной документации. Это файл прожига ПЗУ. К нему инструкция по прожигу. Все остальное - за кружкой пива. Например у Вас был узел на элементах средней степени интеграции. (Документация - Э3, ПЭ3). Теперь это ПЛИС с загрузочным ПЗУ. С тем же набором документации + файл прожига ПЗУ. Кому нужны приключения с программным кодом.
|
|
|
|
|
Jun 5 2008, 11:22
|
Гуру
     
Группа: Свой
Сообщений: 2 198
Регистрация: 23-12-04
Пользователь №: 1 640

|
Цитата(Maverick @ Jun 4 2008, 16:10)  Задача такая есть заказчик (в данном случае допустим я) и есть исполнитель (в лице другого предприятия). Исполнителю было поручено разработать цифровой блок на VHDL (исходные коды предоставил), но для более быстрого понимания работы написанного кода хотелось бы:
.... посмотрите у синопсиса (synopsys.com) как они оформляют свои IP (там может регистрироваться надо - смотреть designware, star ip), понятно, что разработка IP (со всей "требухой") и просто написание кода сильно разные задачи, но пример "как принято" из "свободного" кода считаю удачно (но слышал и другое мнение) сделано у gaisler.com - там VHDL код, набор утилит для сборки/симуляции, доки - не супер, но вполне - все бы субподрядчики так делали, жить было бы легче
|
|
|
|
|
Jun 5 2008, 13:24
|

я только учусь...
     
Группа: Модераторы
Сообщений: 3 447
Регистрация: 29-01-07
Из: Украина
Пользователь №: 24 839

|
Цитата(sazh @ Jun 5 2008, 13:52)  Врядли то, что было поручено исполнителю, можно назвать программным кодом. Это текстовое описание схемной реализации устройства. ... С Вами полностью согласен!  Хорошо, попытаемся абстрагироваться, если это цифровая схема (не важно как она сделана - описана на VHDL или нарисована в схематике, или распаяна на плате отдельными микросхемами цифровой логики), то к ней как к любой схеме должно идти хоть какое-то описание например: функциональная схема, циклограмма работы, описание входов/выходов и т.д. Для программ под Windows так делается!
--------------------
If it doesn't work in simulation, it won't work on the board.
"Ты живешь в своих поступках, а не в теле. Ты — это твои действия, и нет другого тебя" Антуан де Сент-Экзюпери повесть "Маленький принц"
|
|
|
|
|
Jun 6 2008, 05:08
|
Вечный ламер
     
Группа: Модераторы
Сообщений: 7 248
Регистрация: 18-03-05
Из: Томск
Пользователь №: 3 453

|
если не против, добавлю свои 5 капель Цитата(Maverick @ Jun 4 2008, 07:10)  • Файл/документ, содержащий описание всех констант, переменных, сигналов. • Описание работы функциональной модели (схема, конечный автомат состояний (диаграмма состояний конечного автомата), и временная диаграмма работы (скриншоты с ModelSim). • TEST BENCH файл/документ с описанием для возможности моделирования работы. Если с константами и макросами синтеза еще нужно согласиться, то переменные и сигналы это бред Временная диаграмма работы нужна только для внешних интерфейсов, для внутренних ИМХО пустая трата времени. Особенно если есть тестбенчи. Цитата • Подробное описание всех входных и выходных сигналов с предъявляемыми к ним требованиями (например потенциальная или импульсная команда(ее длительность)). В подробном описании не вижу смысла, достаточно краткого описания интерфейса внутреннего модуля. Да и то если модуль тривиальный (мультиплексор, сумматор переносом и т.д.) или код самодокументированый то смысла в этом вообще нет. Цитата • На начальном уровне соединение всех функциональных блоков производить в Schematic Editor (например, Синхрогенератор <=> Модуль связи УПСОС-ПК) (может заменить функциональную/структурную схему). • При использовании ядер из CoreGenerator описать процесс создания. ИМХО полный бред, владеть хдл и при этом рисовать ? И это при наличии функциональной схемы ? Насчет ядер : завернуть ядро в обертку и описать что делает обертка. Этого достаточно. ИМХО в свое описании вы упускаете цель разработки. Решите что вы покупаете : готовое ядро или разработку с кодом. Если покупаете ядро, то все что касается его внутренностей вам не важно. Главное что бы работало и соответствовало ТЗ. (при этом разработчик вообще может пропустить код через обфускатор для сокрытия тайны). Примеры документации можете посмотреть в описании коммерческих/открытых IP А вот если покупаете разработку с кодом, то здесь действительно нужно в договоре отразить все места, для того, что бы дальнейшую поддержку или модернизацию кода, можно было вести самостоятельно без разработчика. Но тут все зависит от условий : 1. если вы покупаете готовую разработку то насчет кода поезд уже ушел, можно требовать только документацию ( и то скорее всего за создание дополнительной документации, нужно будет заплатить) 2. если вы заказываете разработку то тут : ИМХО нужно в обязательном порядке оговорить соглашение об именах, правилах и принципах проектирования !!! это позволит заранее оговорить вопросы Цитата • Файл/документ, содержащий описание всех констант, переменных, сигналов. • По возможности большую программу/схему разбивать на подпрограммы/подсхемы. • В исходном коде программы должны присутствовать комментарии, облегчающие понимание программы • При написании исходного кода программы максимально использовать механизм настраиваемых параметров Generic (например, для разрядности данных, адресов и т. д.). и заставить разработчика писать самодокументированый код. Также требуется тщательная разработка и документирование функциональности и параметров модуля, утверждение плана и методов верификации с описанием тестовых случаев и coner case. Ну ИМХО вот так в кратце. Ну и дополнительное пожелание : все вносите на бумагу с подробным описанием. Иначе разрабочик легко отвертится (конечно в будущем ему с вами может быть и не работать, но в текущем бабло получит). Поэтому не верьте записям в договоре вида "предоставить все документацию, которая использовалась для разработки." Вы думаете что сюда будут входить мини ad-hoc тестбенчи и другая документация об архитектуре подмодулей, а разработчик предоставит функциональную схему высокого уровня абстракции. Также не рекомендую принимать работу в виде проектов CAD с визуализаторами (HdlDesigner) например. Во первых ваша фирма может не использовать данный софт, будут проблемы переносимости кода между разработчиками которые его не используют ну и по хорошему нужно его лицензировать. Удачи !!!
--------------------
|
|
|
|
|
Jun 6 2008, 05:16
|

я только учусь...
     
Группа: Модераторы
Сообщений: 3 447
Регистрация: 29-01-07
Из: Украина
Пользователь №: 24 839

|
Цитата(des00 @ Jun 6 2008, 08:08)  ИМХО нужно в обязательном порядке оговорить соглашение об именах, правилах и принципах проектирования !!!
это позволит заранее оговорить вопросы и заставить разработчика писать самодокументированый код.
Также требуется тщательная разработка и документирование функциональности и параметров модуля, утверждение плана и методов верификации с описанием тестовых случаев и coner case.
Ну ИМХО вот так в кратце.
Ну и дополнительное пожелание : все вносите на бумагу с подробным описанием. Иначе разрабочик легко отвертится (конечно в будущем ему с вами может быть и не работать, но в текущем бабло получит).
Поэтому не верьте записям в договоре вида "предоставить все документацию, которая использовалась для разработки." Вы думаете что сюда будут входить мини ad-hoc тестбенчи и другая документация об архитектуре подмодулей, а разработчик предоставит функциональную схему высокого уровня абстракции.
Также не рекомендую принимать работу в виде проектов CAD с визуализаторами (HdlDesigner) например. Во первых ваша фирма может не использовать данный софт, будут проблемы переносимости кода между разработчиками которые его не используют ну и по хорошему нужно его лицензировать.
Удачи !!! Что такое самодокументированый код? поясните пожалуста! И расскажите о "оговорить соглашение об именах, правилах и принципах проектирования !!!" и "Насчет ядер : завернуть ядро в обертку и описать что делает обертка. Этого достаточно. " поподробнее, плиз
--------------------
If it doesn't work in simulation, it won't work on the board.
"Ты живешь в своих поступках, а не в теле. Ты — это твои действия, и нет другого тебя" Антуан де Сент-Экзюпери повесть "Маленький принц"
|
|
|
|
|
Jun 6 2008, 05:37
|

Electrical Engineer
     
Группа: СуперМодераторы
Сообщений: 2 163
Регистрация: 4-10-04
Пользователь №: 778

|
Maverick дабы не придумывать велосипед и экономить время - можете рекомендовать смотреть 5ю главу RMM: RTL Coding Guidelines (параметры, выбор именования сигналов, написание "прозрачного кода", языковая переносимость, использование бибилиотек, реокмендации по схемам сброса и такта, деление проекта на модули)
а по поводу перечня файлов в комплекте поставки - это параграф 9.1.1 там же (в принципе справедлив и для ПЛИС): Soft Macro Deliverables.
по поводу документирования алгоритмов: как минимум должна быть общая и помодульная функциональная схемы + структурная (RTL) там, где это необходимо (т.е. существуют особенности кодирования при реализации)
мне очень нравится подход Xilinx в описаниях к ЦОС-блокам CoreGen: datasheet - фактически статья-руководство по написанию соответствующего блока, с достаточно хорошим изложением теории работы, функциональными схемами и ссылками на необходимую литературу в конце документа.
--------------------
|
|
|
|
|
Jun 6 2008, 06:19
|

я только учусь...
     
Группа: Модераторы
Сообщений: 3 447
Регистрация: 29-01-07
Из: Украина
Пользователь №: 24 839

|
Цитата(Doka @ Jun 6 2008, 08:37)  Maverick дабы не придумывать велосипед и экономить время - можете рекомендовать смотреть 5ю главу RMM: RTL Coding Guidelines (параметры, выбор именования сигналов, написание "прозрачного кода", языковая переносимость, использование бибилиотек, реокмендации по схемам сброса и такта, деление проекта на модули) а по поводу перечня файлов в комплекте поставки - это параграф 9.1.1 там же (в принципе справедлив и для ПЛИС): Soft Macro Deliverables. Soft Macro Deliverables RMM: RTL Coding Guidelines А не могли бы Вы дать ссылку либо эти файл, плиз Цитата(des00 @ Jun 6 2008, 08:08)  если не против, добавлю свои 5 капель Конечно не против  С Вами практически со всем согласен, но просто на просьбы выдать кроме кода еще хотя бы тестбенч файл и хоть какое то руководство пользователя(как говорится) - они отвечали зачем это тебе или тут и так все понятно или работает и пользуйся. Соответственно я начал рыться и искать как от них хоть чего то добиться, кроме исходного кода. Когда показал перень документов котрые хотел бы видеть (см. выше), то у них ответ постой тестбенчи мы писать не умеем и пользуемся осцилографом, а остальное описание (как они это называют обучение) за отдельную плату
--------------------
If it doesn't work in simulation, it won't work on the board.
"Ты живешь в своих поступках, а не в теле. Ты — это твои действия, и нет другого тебя" Антуан де Сент-Экзюпери повесть "Маленький принц"
|
|
|
|
|
Jun 6 2008, 09:40
|

Местный
  
Группа: Свой
Сообщений: 468
Регистрация: 13-10-06
Из: Россия, Томск
Пользователь №: 21 291

|
Все правильно. Разработчики не любят предоставлять сопроводительную документацию, а особенно такую подробную, ведь в этом случае вы фактически берете их наработки, на которых они и живут. Был случай, когда одна контора отказалась от разработки, когда заказчик пожелал увидеть исходники всех используемых ими модулей. Они сказали так: на разработку библиотек мы потратили очень много времени, и их стоимость превышает ваш заказ десятикратно, либо повышайте соответственно стоимость гонорара, или идите "лесом". Может получится так, что внутренную документацию вам не предоставять ни за какие деньги, всегда оговариваете это на этапе ТЗ.
|
|
|
|
|
Jun 6 2008, 10:28
|
Вечный ламер
     
Группа: Модераторы
Сообщений: 7 248
Регистрация: 18-03-05
Из: Томск
Пользователь №: 3 453

|
Цитата(Maverick @ Jun 6 2008, 01:19)  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. вы заказали разработку с покупкой кода и они ведут себя так, то сами виноваты. Спрашивайте манагеров почему подписали договор на таких условиях!!! Это по сути деньги выкинули в трубу, гарантий саппорта никаких, в случае смены платформы, модернизации почти полная переписка. Рекомендации : с такими командами аутсорсеров не работать. В вашем положении постараться донести перспективы до начальства и договориться с аутсорсерами по хорошему, ну и манагеров потрясти (за что они свой хлеб едят). Удачи!!!
--------------------
|
|
|
|
|
Jun 14 2008, 14:36
|

я только учусь...
     
Группа: Модераторы
Сообщений: 3 447
Регистрация: 29-01-07
Из: Украина
Пользователь №: 24 839

|
Цитата(des00 @ Jun 6 2008, 13:28)  так называемые naming convention и design rules это простые правила которых нужно придерживаться при создании кода. Примеры для ХДЛ есть на этом форуме, в сети, в книгах Ben Cohen, Janic Bergeron а и т.д. Если придерживаться этих правил тогда смена разработчика будет происходить менее болезненно. обертка - wrapper, black-box. модуль созданный по принятым соглашениям, в котором ядро вставлено как под-модуль. Облегчает понимание, переход между архитектурами и т.д. Поделитесь, плиз, данной литературой (книги Ben Cohen, Janic Bergeron и как делается обертка - wrapper, black-box), либо дать ссылку на сайты где могу почитать об этом
--------------------
If it doesn't work in simulation, it won't work on the board.
"Ты живешь в своих поступках, а не в теле. Ты — это твои действия, и нет другого тебя" Антуан де Сент-Экзюпери повесть "Маленький принц"
|
|
|
|
|
Jun 24 2008, 20:43
|
Частый гость
 
Группа: Свой
Сообщений: 80
Регистрация: 17-05-08
Из: Питер
Пользователь №: 37 575

|
Soft Macro Deliverables RMM: RTL Coding Guidelines Подскажите где лежит эта книга на ФТП. не смог ее найти
|
|
|
|
|
  |
2 чел. читают эту тему (гостей: 2, скрытых пользователей: 0)
Пользователей: 0
|
|
|