Vivado и Git

Материал из SRNS
Перейти к: навигация, поиск

Содержание

HOWTO only

К черту подробности! Как собрать bit-ник?!


Введение

Разработка под ПЛИС и СНК отличается монструозностью IDE и проектов в них. Это касается как сложности и нестабильности самого процесса, так и иерархии файлов и их размера.

Например, проект Импалы, собираемый в IDE Xilinx ISE, на диске занимает около 5 Гб. При этом большая часть файлов обновляется при любой манипуляции в IDE, часть из файлов - бинарные. Одним словом - ад для систем контроля версий.

К счастью, в Vivado разработчики сделали работу над ошибками.

Чего хотим мы?

  • Иметь возможность откатиться к старой версии дизайна.
  • Разворачивать и собирать дизайн на любой машине на основе одного-двух репозиториев.
  • Делать частые коммиты без страха за разрастающийся размер репозитория, т.е. коммититься должны файлы малого размера, рукописные, а не сгенерированные программой.
  • Легко переключаться между ветками.

Особенности наших проектов:

  • Используется Zynq, т.е. помимо PL части нужна и PS.
  • В разных дизайнах используются одни и те же модули (оформленные в виде HDL, а не IP блоков).
  • Используются родные Xilinx'овские IP модули (сериалайзеры, буферы, шины, сбросы и т.п.).

О Project и NonProject workflow

Разработчики Vivado выделяют два подхода к ведению проекта: project и non-project.

В первом случае мы активно пользуемся GUI, имеем файл проекта .xpr. Во втором - делаем упор на сборку на основе tcl-скриптов, т.е. реализуем unix-way.

По причине ограниченности наших навыков работы с Vivado, я пока решил остановиться на первом варианте - project workflow, т.е. предполагающем тесное взаимодействие с GUI.

Какие файлы бывают в дизайне Vivado?

Типы файлов, которые Vivado относит к source'м:

  • HDL and netlist files: Verilog (.v), SystemVerilog (.sv), VHDL (.vhd), and EDIF (.edf)
  • C based source files (.c)
  • Tcl files, run scripts, and init.tcl (.tcl)
  • Logical and Physical Constraints (.xdc)
  • IP core files (.xci)
  • IP core container (.xcix)
  • IP integrator block design files (.bd)
  • Design Checkpoint files (.dcp)
  • System Generator subsystems (.sgp)
  • Side files for use by related tools (например, “do”-файлы для симулятора)
  • Block Memory Map files (.bmm, .mmi)
  • Executable and Linkable Format files (.elf)
  • Coefficient files (.coe)

Что хранить в Git'е?

Наша точка зрения

Что "рукописного" мы вносим в проект и хотели бы сохранять в репозитории?

  • Модули на языке Verilog (.v)
  • Testbench'и (_tb.v)
  • Входные тестовые векторы для tb
  • Настройки Xilinx'овских модулей в Block Diagram (.bd)
  • Описание ограничений (.xdc)
  • Описание портов и их соединение с сигналами модулей (.xdc)
  • Коэффициенты фильтров (.coe)
  • Настройки экранов в симуляторах (.wcfg)

Точка зрения Xilinx

Xilinx предлагает два варианта в зависимости от того, какой набор файлов будет храниться в системе контроля версий:

  • держать в репозитории рекомендуемый набор исходников,
  • держать в репозитории минимальный набор исходников.

Минимальный набор исходников позволяет гарантированно восстановить весь проект, если используется та же версия Vivado. Если версии Vivado отличаются, то гарантий нет.


Рекомендуемый набор упрощает переход между разными версиями Vivado и, как утверждается, уменьшает время компиляции.


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

Разделение песочницы и исходных файлов

Когда мы создаем новый дизайн в Vivado, то получаем по-умолчанию структуру каталогов, в которой перемешаны генерируемые и исходные файлы. Есть директории .srcs, .cache, .runs, .data, .hw, .ip_users_files, .sim и т.д. Идея заключается в том, чтобы выкинуть вовне исходные файлы и держать их в системе контроля версий, а в каталоге проекта оставить только генерируемые:

20160304 proj5.png

При выделении исходных файлов в отдельные каталоги конечная структура определяется разработчиком исходя из собственных предпочтений. В репозиторий кладутся только исходные файлы и tcl-скрипт, который позволяет воссоздать каталоги песочницы с генерируемыми файлами. В проекте Oryx SomZ (gitlab.srns.ru/git/src/fpga/) получилось так:

20160325 vivado revolution.png


Шаг 1 для желающих собрать bit-файл: получаем исходные файлы

Настало время сделать первый практический шаг по сборке нового bit-ника - получить описанные выше исходники.

Заводим каталог под всея проект:

korogodin@Diod:~/$ mkdir Oryx
korogodin@Diod:~/$ cd Oryx

Мы готовы клонировать git-репозиторий. Для этого потребуется аккаунт и права доступа к проекту src:

korogodin@Diod:~/Oryx$ git clone ssh://git@srns.ru:221/git/src
Cloning into 'src'...
remote: Counting objects: 20490, done.
remote: Compressing objects: 100% (8449/8449), done.
remote: Total 20490 (delta 13181), reused 18342 (delta 11414)
Receiving objects: 100% (20490/20490), 787.09 MiB | 143.00 KiB/s, done.
Resolving deltas: 100% (13181/13181), done.
Checking connectivity... готово.

Среди прочего, мы получили желанные исходные файлы прошивки PL-части нашего СНК. Они расположены в каталоге fpga:

korogodin@Diod:~/$ cd src/fpga
korogodin@Diod:~/Oryx/src/fpga$ ls
bd  constr  prj_somz.tcl  sub  verilog

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

korogodin@Diod:~/Oryx/src/fpga$ git submodule update --init
korogodin@Diod:~/Oryx/src/fpga$ cd sub
korogodin@Diod:~/Oryx/src/fpga/sub$ tree -L 2 sub
.
├── acquisition
│   ├── bin
│   ├── doc
│   ├── IPgen
│   ├── matlab
│   ├── sdk
│   ├── tb
│   └── verilog
├── correlator
│   ├── tb
│   └── verilog
├── dsp
│   ├── tb
│   └── verilog
├── serializer_zynq
│   └── verilog
└── sync
    └── verilog

Ура, у нас есть все нужные для сборки bit-ника исходные файлы!

Скрипт восстановления песочницы

Т.к. мы остановились на project workflow, то по исходникам из репозитория нужно восстановить всю песочницу проекта. Делает это специальный tcl-скрипт регенерации проекта, который для дизайна Oryx SomZ назван prj_somz.tcl:


Что есть интересного в этом скрипте:

  • Название проекта и относительное расположение песочницы
  • Указание платформы
  • Указание топового модуля
  • Настройка симулятора
  • Подключение к проекту различных наборов файлов - Verilog-исходников, TB, IP, .xdc и т.д.
  • Настройки синтеза (с указанием кристалла!)
  • Настройки имплементации (с указанием кристалла!)

Кроме того, в конец этого скрипта я внес перекомпиляцию Block Design при первом запуске, создание HW Platform, BSP для SDK и подключение проекта прошивки для Microblaze (используется блоком поиска).

Новый скрипт восстановления из существующего проекта можно получить через GUI Vivado (File->Write Project Tcl) или через TCL-консоль командой write_project_tcl:

pwd
cd [get_property DIRECTORY [current_project]]
pwd
write_project_tcl -force prj_somz.tcl

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

Шаг 2 для желающих собрать bit-файл: восстанавливаем песочницу

Скрипт регенерации песочницы проще всего запустить непосредственно через Vivado. При этом скрипт (а так же block design, IP-ядра и т.д.) подходит только к определенной версии среды, поэтому первым делом следует узнать требуемую версию в заголовке файла:

korogodin@Diod:~/Oryx/src/fpga$ head -n 2 prj_somz.tcl
#
# Vivado (TM) v2015.3 (64-bit)

Как следует из заголовка, необходимо использовать версию 2015.3.

Внимание. Скрипт необходимо запускать из директории, в которой расположен файл регенерации проекта prj_somz.tcl!

Запуск скрипта через командную строку

Через командую строку в Linux (обращаю внимание, что я нахожусь в каталоге ~/Oryx/src/fpga/):

korogodin@Diod:~/Oryx/src/fpga$ /opt/Xilinx/Vivado/2015.3/bin/vivado -source prj_somz.tcl

Запустится Vivado, начнется выполнения скрипта.

Запуск скрипта через Vivado

Второй вариант (альтернативный) - запустить скрипт из Vivado. Для этого запускаем Vivado нужной версии. В Tcl Console переходим в каталог с prj_somz.tcl и запускаем его с помощью команды source:

cd ~/Oryx/src/fpga
source prj_somz.tcl

Результат исполнения скрипта

Скрипт создает песочницу и файл проекта. Добавляет к проекту внешние исходные файлы. Настраивает правила синтеза и имплементации. Подключается уже собранный Elf-файл для прошивки MicroBlaze (лежит в репозитории в acquisition/bin, скопированный туда руками ранее).

После этого перекомпилируется Block Design. Для проекта прошивки MicroBlaze в песочнице создается somz.sdk, в него добавляется HW Platform и собирается BSP (microblaze_0, standalone). К проекту подключаются исходники прошивки MicroBlaze из сабмодуля acquisition.

20160325 vivado revolution2.png

Шаг 3 для желающих собрать bit-файл: Generate bitstream со старым elf-файлом для Microblaze

По завершению выполнения скрипта prj_somz.tcl мы имеем готовую к работе настроенную среду:

20160326 vivado revolution3.png

Если не требуется вносить изменения в программу MicroBlaze'а, используемого в блоке поиска, то можно воспользоваться готовым elf-файлом из acquisition/bin. Настраиваем число каналов коррелятора, размер ядра блока поиска, тип корреляторов и т.п. в global_param.v и запускам Generate Bitstream слева снизу в Vivado. Процесс пошел!

Если повезет, то через несколько минут/часов/дней мы получим bit-файл, готовый для прошивки в Oryx (impl_2 - набор правил имплементации, описан в prj_somz.tcl):

korogodin@Diod:~/Oryx/src/fpga$ find ./ -name *.bit
/home/korogodin/Oryx/src/fpga/prj_somz/somz.runs/impl_2/somz.bit

Шаг 4 для желающих собрать bit-файл: Generate bitstream с новым elf-файлом для Microblaze

Если всё-таки нужны правки в прошивке MicroBlaze'а, то придется открывать SDK. Для этого в Vivado следует нажать File->Launch SDK. Открывается XSDK.

Проект прошивки (mcs_facq) изменяется и компилируется в XSDK. Результат лежит в каталоге Debug внутри сабмодуля:

korogodin@Diod:~/Oryx/src/fpga/sub/acquisition/sdk/mcs_facq/Debug$ ls mcs_facq.elf
mcs_facq.elf

Если он нас удовлетворяет, то заменяем им файл в каталоге acquisition/bin и собираем bit-файл, как указано на Шаге 3.

Bonus: Автоматическое подключение проекта прошивки MicroBlaze в SDK

Проект прошивки, BSP, HW Platform подключается автоматически скриптом prj_somz.tcl при регенерации проекта. Для этого в нем используется следующий хак:

exec xsdk -batch -eval "sdk set_workspace [file normalize "$proj_dir/$prj_name.sdk"]; sdk create_hw_project -name $hw_platform_name -hwspec [file normalize "$proj_dir/$prj_name.sdk/$topmodule_name.hdf"]; sdk create_bsp_project -name $facq_bsp_name -hwproject $hw_platform_name -proc $facq_proc_name -os standalone; exec xsdk -eclipseargs -application org.eclipse.cdt.managedbuilder.core.headlessbuild -import [file normalize "$origin_dir/sub/acquisition/sdk/$facq_prj_name/"] -data [file normalize "$proj_dir/$prj_name.sdk"] -vmargs -Dorg.eclipse.cdt.core.console=org.eclipse.cdt.core.systemConsole; exit"

Этот хак получен методом тыка, своё дело выполняет, но приводит к сообщению об ошибке и остановке исполнения скрипта prj_somz.tcl. Пока так.

Bonus: Файл .gitignore

В ~/Oryx/src/fpga расположен свой файл .gitignore:


Как видно из файла, каталог с песочницей (с проектом) обязательно должен начинаться с prj.

В сабмодуле acquisition/sdk также используется свой файл .gitignore, скрывающий от git'а каталоги Debug и Release.

Bonus: О изменениях в файлах проекта приложения в SDK

Настройки проекта приложения для MicroBlaze находятся в файле acquisition/sdk/mcs_facq/.cproject. Чтобы проект приложения легко подключался непосредственно из сабмодуля в .cproject изменены относительные пути до bsp на

${workspace_loc:/mcs_facq_bsp}
.

Bonus: О хранении Block Design в системе контроля версий

Информация к размышлению. В итоге выбран вариант первый - с хранением BD файла в репозитории.

Вариант с хранением .BD файла в репозитории

Документ XAPP1165 опускает тему сохранения Block Desing'ов в git'е. Vivado же предполагает активное использование IP-интегратора. Если в проекте присутствует block design, то в скрипт восстановления добавляются строки вида:

# Set 'sources_1' fileset object
set obj [get_filesets sources_1]
set files [list \
 "[file normalize "$origin_dir/readWriteToReg/readWriteToReg.srcs/sources_1/bd/design_1/design_1.bd"]"\
]
add_files -norecurse -fileset $obj $files

# Set 'sources_1' fileset file properties for remote files
set file "$origin_dir/readWriteToReg/readWriteToReg.srcs/sources_1/bd/design_1/design_1.bd"
set file [file normalize $file]
set file_obj [get_files -of_objects [get_filesets sources_1] [list "*$file"]]
if { ![get_property "is_locked" $file_obj] } {
  set_property "generate_synth_checkpoint" "0" $file_obj
}

Из этих строк можно сделать вывод, что для восстановления Block Diagram достаточно самого .bd файла. Файл .bd является текстовым XML документом, размер несколько Кб, т.е. для хранения в СКВ не является проблемой.

Я попробовал вывести design_1.bd за пределы песочницы, в каталог ./bd/, соответствующим образом поправил скрипт восстановления проекта. Скрипт успешно восстановил после этого проект, но при синтезе и имплементации Vivado сгенерировала множество файлов в каталоге ./bd:


20160304 proj7.png


Какой выход в этом случае? Видимо только блокировать эти файлы через .gitignore, что неприятно.

Какое преимущество? Не нужны ручные правки скрипта восстановления проекта.

UPDATE: Замечен ещё недостаток. Если в проекте лежит elf'ник для microblaz'а, то в BD файле путь к нему заменяется полным. В итоге BD файл будет постоянно обновляться при отсутствии реальных изменений.

Вариант с хранением скрипта восстановления .BD файла в репозитории

Xilinx предлагает хранить не bd файл, а tcl-скрипт, его регенерирующий. Создать скрипт можно через File->Export при открытом Block Design в IP Integrator'е. Минус этого метода - наличие ещё одного скрипта, который нужно поддерживать в актуальном состоянии вручную.

Ссылки

Персональные инструменты
Пространства имён

Варианты
Действия
SRNS Wiki
Рабочие журналы
Приватный файлсервер
QNAP Сервер
Инструменты
Печать/экспорт