MPSU/APS
1
0
Fork 0
mirror of https://github.com/MPSU/APS.git synced 2026-06-10 11:13:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

English version draft

Browse Source 
Assisted-by: Claude:claude-4.6-sonnet
This commit is contained in:
Andrei Solodovnikov
2026-04-12 13:53:25 +03:00
parent 63260f434e
commit f3fcd27387
74 changed files with 5133 additions and 5875 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
Vivado Basics/01. New project.md
View File

@@ -1,76 +1,77 @@
# Создание нового проекта в Vivado
# Creating a New Project in Vivado
Для того, чтобы создать новый проект в Vivado для отладочного стенда Nexys A7, следуйте следующему порядку выполнения действий.
To create a new project in Vivado for the Nexys A7 development board, follow the steps below.
1. Запустите Vivado.
2. Нажмите `Create Project`.
3. В открывшемся окне нажмите `Next`.
4. Введите название проекта (без пробелов и кириллических символов) → Выберите папку для проекта → Установите селектор `Create project subdirectory` → Нажмите `Next`.
5. Выберите RTL Project → Установите селектор `Do not specify sources at this time` → Нажмите `Next`.
6. Выставьте следующие фильтры, чтобы сузить список ПЛИС:
1. Launch Vivado.
2. Click `Create Project`.
3. In the dialog that appears, click `Next`.
4. Enter the project name (no spaces or Cyrillic characters) → Select the project folder → Enable the `Create project subdirectory` checkbox → Click `Next`.
5. Select RTL Project → Enable the `Do not specify sources at this time` checkbox → Click `Next`.
6. Set the following filters to narrow the FPGA list:
- Family: `Artix 7`
- Package: `csg324`,
- Speed: `-1`.
- Package: `csg324`
- Speed: `-1`
На _рис. 1_ показано окно с примененными фильтрами.
7. В списке выберите ПЛИС `xc7a100tcsg324-1` (расположена в самом низу) → Нажмите `Next`.
8. Нажмите `Finish`
_Fig. 1_ shows the window with the applied filters.
7. In the list, select the FPGA `xc7a100tcsg324-1` (located at the bottom) → Click `Next`.
8. Click `Finish`.
![../.pic/Vivado%20Basics/01.%20New%20project/fig_01.png](../.pic/Vivado%20Basics/01.%20New%20project/fig_01.png)
_Рисунок 1. Пример заполнения фильтров для выбора ПЛИС, используемой в Nexys A7._
_Figure 1. Example of filter settings for selecting the FPGA used in Nexys A7._
После нажатия на `Finish`, откроется окно созданного проекта. Выполним его настройку. Для этого, в окне `Flow Navigator`, расположенном в левой части Vivado необходимо нажать на кнопку `Settings`.
After clicking `Finish`, the newly created project window will open. Now configure the project settings. To do this, click the `Settings` button in the `Flow Navigator` panel on the left side of Vivado.
## Настройки для нового проекта
## New Project Settings
### Настройка времени моделирования
### Simulation Time Configuration
В первую очередь, нам необходимо указать какое количество времени работы схемы будет моделироваться при запуске симуляции. Для этого, в группе `Project Settings` необходимо выбрать `Simulation`. В открывшейся странице выбрать вкладку `Simulation`, и в поле `xsim.simulate.runtime` указать значение `1s`. Это означает, что по умолчанию будет запускаться симуляция одной секунды времени работы схемы. На _рис. 2_. показан пример данной настройки. Пока что не закрывайте окно настроек.
First, specify how much simulation time will be modeled when the simulation is launched. In the `Project Settings` group, select `Simulation`. On the page that opens, go to the `Simulation` tab and set the `xsim.simulate.runtime` field to `1s`. This means that by default, one second of circuit operation will be simulated. _Fig. 2_ shows an example of this setting. Do not close the settings window yet.
![../.pic/Vivado%20Basics/01.%20New%20project/fig_02.png](../.pic/Vivado%20Basics/01.%20New%20project/fig_02.png)
_Рисунок 2. Пример настройки времени симуляции._
_Figure 2. Example of simulation time configuration._
Одна секунда — это очень большое значение, на многие порядки превышающее время симуляции в большинстве лабораторных работ. Однако верификационное окружение во всех лабораторных будет досрочно останавливать моделирование. Установив подобное большое значение, мы избавимся от необходимости указывать нужное нам время симуляции при каждой симуляции: она просто будет идти, пока не остановится, но в случае, если верификационное окружение почему-то не остановит моделирование, мы будем знать, что оно остановится само по достижении времени в 1с.
One second is a very large value, many orders of magnitude greater than the simulation time in most lab assignments. However, the testbench in every lab will stop the simulation early. By setting such a large value, we avoid having to specify the simulation duration each time: the simulation will simply run until it stops on its own, but if the testbench fails to stop it for some reason, we know it will stop automatically after 1 s.
## Настройки Vivado
## Vivado Settings
### Настройки появления всплывающих окон
### Pop-up Window Configuration
Выполним также настройку отображения всплывающих окон при запуске некоторых инструментов. Для этого необходимо перейти в `Window Behavior->Confirmations` в группе настроек, общей для всех проектов (Tool Settings) и снять выбор с опций, выделенных на _рисунке 3_ красными прямоугольниками.
Это позволит избавиться от назойливых всплывающих окон, на которых в большинстве случаев всегда нажимается кнопка "OK".
Also configure the pop-up window behavior when launching certain tools. Go to `Window Behavior -> Confirmations` in the global settings group (Tool Settings) and uncheck the options highlighted with red rectangles in _Figure 3_.
This will eliminate the persistent pop-up windows that in most cases simply require clicking "OK".
![../.pic/Vivado%20Basics/01.%20New%20project/fig_03.png](../.pic/Vivado%20Basics/01.%20New%20project/fig_03.jpg)
_Рисунок 3. Пример настройки появления всплывающих окон._
_Figure 3. Example of pop-up window configuration._
### Настройки автоматического дополнения кода
### Code Completion Settings
При работе в Vivado вам может показаться неудобной его встроенная функция автоматического дополнения кода. Пока она активна, Vivado пытается предложить подходящие ключевые слова в момент набора кода (см. _рисунок 4_).
When working in Vivado, you may find the built-in code completion feature inconvenient. While active, Vivado attempts to suggest matching keywords as you type (see _Figure 4_).
![../.pic/Vivado%20Basics/01.%20New%20project/fig_04.jpg](../.pic/Vivado%20Basics/01.%20New%20project/fig_04.jpg)
_Рисунок 4. Пример включенной функции автодополнения._
_Figure 4. Example of the code completion feature enabled._
В данной ситуации, нажатие на клавишу <kbd>Enter</kbd> не перенесет курсор на новую строку. Вместо этого, будет выбран активный вариант в списке дополнения и ключевое слово `end` будет дополнено до `endcase`. Чтобы список пропал, необходимо нажать на клавишу <kbd>ESC</kbd>, либо щелкнуть курсором где-либо вне данного списка.
In this situation, pressing <kbd>Enter</kbd> will not move the cursor to a new line. Instead, the active suggestion will be selected and the keyword `end` will be completed to `endcase`. To dismiss the list, press <kbd>ESC</kbd> or click anywhere outside the list.
Для того, чтобы отключить появление данного списка (или сделать так, чтобы он появлялся только по команде), необходимо в настройках Vivado перейти к разделу `Text Editor -> Code completion`. Вы можете выбрать один из трёх вариантов (см. _рисунок 5_):
To disable the list (or configure it to appear only on demand), go to `Text Editor -> Code completion` in the Vivado settings. You can choose one of three options (see _Figure 5_):
1. `Display list of choices on demand` — список появится только когда вы нажмете <kbd>CTRL</kbd>+<kbd>Space</kbd>.
2. `Display list of choices as you type` — список будет появляться автоматически по мере набора кода.
3. `Disable code completion` — список не будет появляться никогда.
1. `Display list of choices on demand` — the list appears only when you press <kbd>CTRL</kbd>+<kbd>Space</kbd>.
2. `Display list of choices as you type` — the list appears automatically as you type.
3. `Disable code completion` — the list never appears.
![../.pic/Vivado%20Basics/01.%20New%20project/fig_05.jpg](../.pic/Vivado%20Basics/01.%20New%20project/fig_05.jpg)
_Рисунок 5. Настройки раздела `Code completion`._
_Figure 5. Settings for the `Code completion` section._
### Настройки шрифта
### Font Settings
В группе настроек `Text Editor` вы также можете настроить и размер, цвет и шрифт, используемый текстовым редактором. Сделать это можно в разделе `Fonts and colors` (см. _рисунок 6_).
In the `Text Editor` settings group, you can also configure the size, color, and font used by the text editor. This is done in the `Fonts and colors` section (see _Figure 6_).
![../.pic/Vivado%20Basics/01.%20New%20project/fig_06.jpg](../.pic/Vivado%20Basics/01.%20New%20project/fig_06.jpg)
_Рисунок 6. Настройки раздела `Fonts and colors`._
_Figure 6. Settings for the `Fonts and colors` section._
На этом создание и настройка проекта завершена.
Project creation and configuration is now complete.

28
Vivado Basics/02. Flow Navigator.md
View File

@@ -1,24 +1,24 @@
# Навигатор по маршруту проектирования (Flow Navigatior)
# Design Flow Navigator (Flow Navigator)
После создания нового проекта, откроется основное окно проекта Vivado, представленного на _рис. 1_.
After creating a new project, the main Vivado project window shown in _Fig. 1_ will open.
![../.pic/Vivado%20Basics/02.%20Flow%20Navigator/fig_01.png](../.pic/Vivado%20Basics/02.%20Flow%20Navigator/fig_01.png)
_Рисунок 1. Окно пустого проекта Vivado._
_Figure 1. Empty Vivado project window._
Визуально, основное окно Vivado разделено на две части: тонкую полоску окна `Flow Navigator`, расположенную слева, и основное окно `Project Manager`, расположенную справа. Дело в том, что Vivado представляет собой мощную многофункциональную интегрированную среду разработки (Integrated Design Environment, IDE), состоящую из нескольких подпрограмм, которые для удобства упакованы в одну общую графическую оболочку. `Flow Navigator` позволяет переключаться между этими подпрограммами в рамках одного окна.
Visually, the main Vivado window is divided into two parts: a narrow `Flow Navigator` panel on the left and the main `Project Manager` window on the right. Vivado is a powerful, multi-functional integrated design environment (IDE) composed of several sub-applications that are packaged together into a single graphical shell for convenience. The `Flow Navigator` allows you to switch between these sub-applications within a single window.
Маршрут проектирования подразумевает цикличное повторение шагов:
The design flow involves cyclically repeating the following steps:
1. Написание кода.
2. Анализ получившейся схемы на предмет легко обнаруживаемых ошибок.
3. Симуляция схемы
4. Синтез
5. Имплементация
6. Генерация двоичного кода для прошивки ПЛИС
1. Writing code.
2. Analyzing the resulting schematic for easily detectable errors.
3. Simulating the schematic.
4. Synthesis.
5. Implementation.
6. Generating a bitstream for programming the FPGA.
Подробнее о некоторых из этапов рассказано в главе "Этапы реализации проекта в ПЛИС".
Some of these steps are described in more detail in the chapter "FPGA Implementation Steps".
Если на каком-то из этапов обнаруживается ошибка, происходит возврат на шаг 1 и повторение всего процесса заново. Благодаря `Flow Navigator` вам не нужно постоянно запускать для каждого этапа новую программу, вы можете быстро переходить от этапа к этапу в рамках одного графического окна.
If an error is found at any step, the process returns to step 1 and repeats from the beginning. Thanks to the `Flow Navigator`, you do not need to launch a separate application for each step — you can quickly move between stages within a single graphical window.
При этом, в зависимости от того, какую именно подпрограмму вы активировали во `Flow Navigator`, соответствующим образом изменится основная часть окна Vivado. После создания проекта автоматически активируется программа `Project Manager` (выделено бирюзовым в окне `Flow Navigator`), именно поэтому в основном окне открылся менеджер проекта.
Depending on which sub-application is activated in the `Flow Navigator`, the main area of the Vivado window changes accordingly. When a project is created, the `Project Manager` is activated automatically (highlighted in teal in the `Flow Navigator`), which is why the Project Manager opens in the main window.

152
Vivado Basics/03. Project manager.md
View File

@@ -1,99 +1,99 @@
# Менеджер проекта (Project Manager)
# Project Manager
Окно Project Manager позволяет управлять проектом: добавлять и редактировать исходные коды проекта, изучить краткое ревью по утилизации ресурсов ПЛИС, используемых для реализации проекта, просматривать логи и сообщения о результатах сборки проекта и многое другое.
The Project Manager window allows you to manage the project: add and edit project source files, view a brief summary of FPGA resource utilization, browse build logs and messages, and much more.
В первую очередь нас интересует окно исходных кодов проекта, которое называется `Design Sources` и представлено на _рис. 1_.
The primary area of interest is the project sources window, called `Design Sources`, shown in _Fig. 1_.
## Окно Design Sources
## The Design Sources Window
Данное окно находится по умолчанию в верхнем левом углу окна Project Manager (в случае, если вы случайно закрыли это окно, вы можете вернуть его обратно через меню `Windows->Sources`).
By default, this window is located in the upper-left corner of the Project Manager window. If you accidentally close it, you can restore it via the `Windows -> Sources` menu.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_01.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_01.png)
_Рисунок 1. Окно исходных кодов проекта._
_Figure 1. Project sources window._
Данное окно разделено на три вкладки:
The window is divided into three tabs:
1. Иерархия (Hierarchy)
2. Библиотеки (Libraries)
3. Порядок сборки (Compile Order)
1. Hierarchy
2. Libraries
3. Compile Order
В определенных ситуациях в данном окне может появиться и вкладка IP Cores, но в рамках данного курса она нас не интересует.
In certain situations, an IP Cores tab may also appear, but it is not relevant for this course.
Рассмотрим по порядку данные вкладки.
Let us review each tab in order.
### Вкладка Hierarchy
### The Hierarchy Tab
Данная вкладка состоит из четырёх "папок":
This tab contains four "folders":
1. Design Sources;
2. Constraints;
3. Simulation Sources;
4. Utility Sources.
1. Design Sources
2. Constraints
3. Simulation Sources
4. Utility Sources
В рамках текущего курса лабораторных работ мы будем взаимодействовать только с первыми тремя из них.
During this course, we will only work with the first three.
Помните, что несмотря на использование слова "папка", речь идет не о директориях операционной системы. Папки проекта — это всего лишь удобная абстракция для управления иерархией проекта.
Note that despite the use of the word "folder", these are not file system directories. Project folders are simply a convenient abstraction for managing the project hierarchy.
В папке `Design Sources` строится иерархия проектируемых модулей (исходников цифровых схем, которые в будущем могут быть воспроизведены в ПЛИС или заказной микросхеме).
The `Design Sources` folder holds the hierarchy of design modules — source files for digital circuits that may eventually be synthesized to an FPGA or an application-specific integrated circuit (ASIC).
Папка `Constraints` содержит файлы ограничений, помогающих реализовать проект на конкретной ПЛИС (см. ["Этапы реализации проекта в ПЛИС"](../Introduction/Implementation%20steps.md#implementation)).
The `Constraints` folder contains constraint files that help implement the project on a specific FPGA (see ["FPGA Implementation Steps"](../Introduction/Implementation%20steps.md#implementation)).
`Simulation Sources` хранит в себе иерархию верификационного окружения, **включая модули из папки** `Design Sources` — т.е. все модули (как синтезируемые, так и не синтезируемые), которые будут использованы при моделировании.
`Simulation Sources` stores the hierarchy of the verification environment, **including modules from the** `Design Sources` folder — that is, all modules (both synthesizable and non-synthesizable) that will be used during simulation.
> Обратите внимание на то, что вкладка `Hierarchy` не содержит файлов. Здесь отображается иерархия модулей проекта. Один модуль может быть использован несколько раз — и в этом случае он будет столько же раз отображён в иерархии, хотя файл, хранящий описание этого модуля останется один (см. _рис. 6_).
> Note that the `Hierarchy` tab does not show files. It displays the module hierarchy of the project. A single module can be instantiated multiple times — in that case it will appear multiple times in the hierarchy, even though the file describing that module remains a single file (see _Fig. 6_).
#### Добавление файла в проект
#### Adding a File to the Project
Для того, чтобы добавить в проект новый файл, необходимо нажать на значок `+`, расположенный в верхней части окна `Sources` (либо использовать комбинацию горячих клавиш `Alt+A`).
To add a new file to the project, click the `+` icon at the top of the `Sources` window (or use the keyboard shortcut `Alt+A`).
Появится окно добавления исходников. На первой странице этого окна будет необходимо выбрать тип добавляемого файла (см. _рис. 2_).
The Add Sources dialog will appear. On the first page, select the type of file to add (see _Fig. 2_):
- файлы ограничений для синтеза схемы под конкретную ПЛИС (`Constraints`);
- файлы проектируемой схемы (`Design Sources`);
- файлы верификационного окружения проектируемой схемы (`Simulation Sources`).
- Constraint files for synthesizing the design to a specific FPGA (`Constraints`);
- Design source files (`Design Sources`);
- Verification environment files (`Simulation Sources`).
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_02.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_02.png)
_Рисунок 2. Первая страница окна добавления исходников._
_Figure 2. First page of the Add Sources dialog._
В первую очередь мы хотим описать какую-нибудь простую схему, поэтому необходимо убедиться, что активным выбран пункт `Design Sources`. Выбрав, нажимаем `Next`.
Since we want to describe a simple circuit first, make sure `Design Sources` is selected, then click `Next`.
Появится страница, представленная на _рис. 3_, которая предлагает три варианта добавления исходников.
The page shown in _Fig. 3_ will appear, offering three options for adding sources:
1. добавить существующий файл;
2. добавить все имеющиеся файлы в заданной директории;
3. создать новый файл.
1. Add an existing file;
2. Add all files in a specified directory;
3. Create a new file.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_03.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_03.png)
_Рисунок 3. Вторая страница окна добавления исходников._
_Figure 3. Second page of the Add Sources dialog._
Создадим новый файл, нажав на соответствующую кнопку окна. Появится всплывающее окно, предлагающее выбрать тип файла и его имя (см. _рис. 4_). В поле `File Type` выберите `SystemVerilog` (этот тип будет использоваться в качестве основного на протяжении всего курса кроме случаев, когда будет сказано иное). В поле `File Name` задайте имя новому файлу (в рамках примера, имя файла будет `max_min`). Указывать расширение файла не нужно — САПР автоматически его добавит в зависимости от выбранного типа файла. Когда всё будет готово, нажмите на `OK`. После того, как были добавлены (или созданы) все необходимые источники, можно нажать кнопку `Finish` в окне `Add Sources`.
Create a new file by clicking the corresponding button. A pop-up window will appear asking you to choose the file type and name (see _Fig. 4_). In the `File Type` field, select `SystemVerilog` (this type will be used throughout the course unless stated otherwise). In the `File Name` field, enter a name for the new file (in this example, the file name will be `max_min`). You do not need to specify a file extension — the EDA tool will add it automatically based on the selected file type. When ready, click `OK`. After all required sources have been added (or created), click `Finish` in the `Add Sources` dialog.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_04.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_04.png)
_Рисунок 4. Окно создания нового файла._
_Figure 4. New file creation dialog._
В случае, если создавался новый файл, после нажатия на кнопку `Finish` появится окно, предлагающее автоматически создать прототип модуля, указав в графическом интерфейсе направление и разрядность его портов (см. _рис. 5_). В рамках данного примера, откажемся от данного предложения, нажав кнопки `Cancel->Yes`.
If a new file was created, after clicking `Finish` a window will appear offering to automatically generate a module prototype by specifying port directions and widths through the GUI (see _Fig. 5_). For this example, decline the offer by clicking `Cancel -> Yes`.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_05.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_05.png)
_Рисунок 5. Окно описания входов и выходов модуля._
_Figure 5. Module port definition dialog._
После добавления файлов с исходными кодами, Vivado автоматически начнет обновлять иерархию проекта. Вы можете заметить это по появившейся надписи `Updating` с анимацией крутящейся стрелки, показанной на _рис. 6_.
After adding the source files, Vivado will automatically begin updating the project hierarchy. You can notice this by the `Updating` label with a spinning arrow animation shown in _Fig. 6_.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_06.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_06.png)
_Рисунок 6. Уведомление об обновлении иерархии проекта._
_Figure 6. Project hierarchy update notification._
Пока в окне есть данное уведомление, не рекомендуется запускать подпрограммы во `Flow Navigator` (к примеру, пытаться открыть схему, запустить симуляцию/синтез и т.п.), поскольку иерархия проекта ещё не построена и в конечном итоге может либо произойти ошибка, либо будет выполнено действие не для нужного вам модуля.
While this notification is visible, it is not recommended to launch any sub-applications from the `Flow Navigator` (for example, opening a schematic, running simulation or synthesis, etc.), because the project hierarchy has not yet been built and doing so may result in an error or an action being applied to the wrong module.
> В зависимости от того, какие подпрограммы запущены через `Flow Navigator`, в момент вызова окна `Add Sources`, Vivado автоматически будет стараться выбрать наиболее подходящий пункт (что не всегда будет совпадать с вашим намереньем). К примеру, вы описали модуль, запустили симуляцию, чтобы его проверить, а затем решили описать следующий модуль. Из-за того, что в момент вызова окна `Add Sources` в фоне запущена симуляция, в этом окне по умолчанию будет выбран пункт `Simulation Sources`.
> Depending on which sub-applications are active in the `Flow Navigator` at the time the `Add Sources` window is opened, Vivado will attempt to select the most appropriate option automatically (which may not always match your intent). For example, if you described a module, launched a simulation to verify it, and then decided to describe the next module, the `Add Sources` window will default to `Simulation Sources` because the simulation is running in the background at that moment.
После того, как Vivado закончит обновлять иерархию (и, если при создании файла вы отказались указывать порты модуля, нажав на кнопку `Cancel`), рядом с папкой `Design Sources` появится стрелка, позволяющая развернуть эту папку, внутри которой обнаружится подпапка `Non-module Files` с созданным нами файлом. Новый файл пометили таким образом, поскольку он не содержит модуля. Как только в нем окажется описание какого-нибудь модуля, эта подпапка пропадёт.
Once Vivado finishes updating the hierarchy (and if you declined to specify module ports by clicking `Cancel`), an arrow will appear next to the `Design Sources` folder, allowing you to expand it. Inside, you will find a `Non-module Files` subfolder containing the newly created file. The file is labeled this way because it does not yet contain a module. Once a module is described in it, the subfolder will disappear.
Откроем редактор двойным кликом по файлу `max_min.sv` и опишем в нём код, приведённый в листинге 1. В коде _листингов 1-3_ могут содержаться логические ошибки — они запланированы и будут найдены и исправлены в документе "[Руководство по поиску функциональных ошибок](./05.%20Bug%20hunting.md)".
Open the editor by double-clicking `max_min.sv` and describe the code shown in Listing 1. The code in _Listings 1–3_ may contain intentional logical errors — these will be identified and corrected in the document "[Guide to Finding Functional Errors](./05.%20Bug%20hunting.md)".
```Verilog
module max_min(
@@ -117,11 +117,11 @@ module max_min(
endmodule
```
_Листинг 1. Описание модуля max\_min._
_Listing 1. Description of the max\_min module._
Не забудьте сохранить файл после описания в нем модуля нажав в редакторе на значок дискеты, или комбинацию клавиш `Ctrl+S`.
Do not forget to save the file after writing the module by clicking the floppy disk icon in the editor or pressing `Ctrl+S`.
Аналогичным образом, добавьте в `Design Sources` проекта файлы `half_divider` и `vector_abs` и опишите в них модули, представленные в _листингах 2-3_ соответственно (все файлы листингов находятся в репозитории в папке [Vivado Basics/vector_abs](./vector_abs/)). На второй странице окна добавления исходников, представленном на _рис. 3_, вы можете создавать сразу несколько новых файлов. При создании убедитесь, что вы выбрали корректный тип файла.
Similarly, add files `half_divider` and `vector_abs` to `Design Sources` and describe the modules shown in _Listings 2–3_ respectively (all listing files are available in the repository under [Vivado Basics/vector_abs](./vector_abs/)). On the second page of the Add Sources dialog shown in _Fig. 3_, you can create multiple new files at once. Make sure you select the correct file type when creating them.
```Verilog
module half_divider(
@@ -134,7 +134,7 @@ module half_divider(
endmodule
```
_Листинг 2. Описание модуля half\_divider._
_Listing 2. Description of the half\_divider module._
```Verilog
module vector_abs(
@@ -164,9 +164,9 @@ module vector_abs(
endmodule
```
_Листинг 3. Описание модуля vector\_abs._
_Listing 3. Description of the vector\_abs module._
В `Simulation Sources` добавьте файл `tb_vector_abs`, описываемый _листингом 4_.
Add the file `tb_vector_abs` to `Simulation Sources` as described in _Listing 4_.
```Verilog
module tb_vector_abs();
@@ -229,58 +229,58 @@ end
endmodule
```
_Листинг 4. Описание модуля tb\_vector\_abs._
_Listing 4. Description of the tb\_vector\_abs module._
#### Построение иерархии модулей
#### Building the Module Hierarchy
После создания указанных файлов и описания в них модулей из листингов 2-4, иерархия модулей примет следующий вид, представленный на _рис. 7_.
After creating the files listed above and describing the modules from Listings 2–4, the module hierarchy will look as shown in _Fig. 7_.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_07.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_07.png)
_Рисунок 7. Иерархия проекта, представленная в свёрнутом виде._
_Figure 7. Project hierarchy shown in collapsed view._
Нажав на стрелку слева от модуля `vector_abs`, иерархия развернётся (_рис. 8_).
Clicking the arrow to the left of the `vector_abs` module will expand the hierarchy (_Fig. 8_).
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_08.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_08.png)
_Рисунок 8. Иерархия проекта, представленная в развёрнутом виде._
_Figure 8. Project hierarchy shown in expanded view._
Обратите внимание на то, что модуль `vector_abs` выделен жирным относительно других модулей. Такое выделение означает, что данный модуль выбран в качестве **модуля верхнего уровня** (**top-level module**). Это означает, это данный модуль и представляет итоговую схему, которую мы проектируем, и что другие подпрограммы во `Flow Navigator`, такие как `RTL ANALYSIS`, `SYNTHESIS`, `IMPLEMENTATION` и `PROGRAM AND DEBUG` будут обрабатывать именно этот модуль. Если вдруг вы захотите работать с другим модулем (например, с модулем, `half_divider`) — его необходимо пометить вручную в качестве модуля верхнего уровня. Для этого необходимо нажать по нему правой кнопкой мыши, и в выпадающем меню выбрать `Set as Top` (см. _рис. 9_).
Notice that the `vector_abs` module is displayed in bold compared to the other modules. This indicates that it is selected as the **top-level module**. This means it represents the final design being implemented, and other sub-applications in the `Flow Navigator` — such as `RTL ANALYSIS`, `SYNTHESIS`, `IMPLEMENTATION`, and `PROGRAM AND DEBUG` — will process this module. If you want to work with a different module (for example, `half_divider`), you must manually set it as the top-level module. To do so, right-click it and select `Set as Top` from the drop-down menu (see _Fig. 9_).
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_09.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_09.png)
_Рисунок 9. Выбор модуля верхнего уровня (показана середина выпадающего списка)._
_Figure 9. Selecting the top-level module (the middle of the drop-down menu is shown)._
Обратите внимание на то, как строится иерархия проекта. Модули, являющиеся объектами других модулей "вложены" в эти модули. Причем в иерархии проекта сперва указывается имя объекта модуля, затем через двоеточие имя самого модуля. В скобках указывается имя файла, где модуль описан. Модуль, который не содержится в других модулях, не имеет имени объекта модуля (т.к. нет сущности, которая бы этот объект создавала). Если модуль будет содержать несколько объектов одного и того же модуля, в иерархии будут отображены все эти объекты — именно поэтому нужно понимать, чем иерархия модулей отличается от дерева файлов. Несмотря на то, что модуль описан всего в одном файле, в иерархии проекта может встречаться несколько экземпляров одного и того же модуля.
Note how the project hierarchy is structured. Modules that are instantiated inside other modules are "nested" within them. In the hierarchy, the instance name is shown first, followed by a colon and the module name. The file where the module is described is shown in parentheses. A module that is not instantiated inside any other module has no instance name (since there is no entity that creates the instance). If a module contains multiple instances of the same module, all of those instances will be shown in the hierarchy — this is why it is important to understand the difference between the module hierarchy and a file tree. Even though a module is described in a single file, multiple instances of it may appear in the project hierarchy.
#### Ошибки иерархии
#### Hierarchy Errors
В случае, если при создании какого-либо из файлов вы ошиблись с папкой назначения (добавили файл, предназначенный для `Design Sources` в `Simulation Sources` или наоборот), вы можете перенести этот файл в нужную папку без необходимости его удаления и повторного добавления. Для этого кликните по нужному файлу правой кнопкой мыши и выберите `Move to Design/Simulation sources` (см. _рис. 10_).
If you accidentally placed a file in the wrong folder (for example, added a file intended for `Design Sources` to `Simulation Sources` or vice versa), you can move it to the correct folder without deleting and re-adding it. Right-click the file and select `Move to Design/Simulation sources` (see _Fig. 10_).
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_10.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_10.png)
_Рисунок 10. Перенос модуля в нужную папку._
_Figure 10. Moving a module to the correct folder._
После добавления модуля `tb_vector_abs`, посмотрите на иерархию `Simulation Sources`. Обратите внимание на то, что все модули `Design Sources` продублированы в `Simulation Sources`. Это ещё одно отличие от дерева файлов. Физически каждый модуль находится всего в одном файле, здесь представлена иерархия модулей.
After adding the `tb_vector_abs` module, look at the `Simulation Sources` hierarchy. Notice that all `Design Sources` modules are duplicated in `Simulation Sources`. This is another distinction from a file tree. Physically, each module exists in only one file; what is shown here is the module hierarchy.
Можно также заметить, что модуль верхнего уровня в `Simulation Sources` другой. Модуль верхнего уровня в `Simulation Sources` определяет то, какой модуль будет использоваться при симуляции (обычно это тестбенч, внутри которого создан объект проверяемого модуля). Модули верхнего уровня в `Design Sources` и `Simulation Sources` не связаны друг с другом (вам не нужно выбирать модулем верхнего уровня в `Design Sources` тот модуль, что вы будете проверять с помощью тестбенча в `Simulation Sources`).
You will also notice that the top-level module in `Simulation Sources` is different. The top-level module in `Simulation Sources` determines which module will be used during simulation (typically a testbench that instantiates the module under test). The top-level modules in `Design Sources` and `Simulation Sources` are independent — you do not need to set the module being tested as the top-level in `Design Sources` in order to verify it using a testbench in `Simulation Sources`.
Давайте изменим в модуле `tb_vector_abs` название модуля `vector_abs`, использовавшееся при создании объекта `DUT` (например на `vector`). Получившаяся иерархия модулей представлена на _рис. 11_.
Let us change the module name `vector_abs` used when instantiating the `DUT` object in `tb_vector_abs` (for example, to `vector`). The resulting module hierarchy is shown in _Fig. 11_.
![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_11.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_11.png)
_Рисунок 11. Иерархия проекта с отсутствующим модулем._
_Figure 11. Project hierarchy with a missing module._
Иерархия обновилась, но поскольку в проекте не существует модуля с названием `vector`, это отобразилось соответствующим образом. Поскольку модуль `vector_abs` не является частью модуля `tb_vector_abs`, он перестал быть вложенным модулем и разместился рядом в `Simulation Sources` (в `Design Sources` иерархия осталась прежней, т.к. изменения коснулись только модуля `tb_vector_abs`, расположенного в `Simulation Sources`).
The hierarchy was updated, but since there is no module named `vector` in the project, this is reflected accordingly. Since `vector_abs` is no longer part of `tb_vector_abs`, it is no longer a nested module and appears alongside it in `Simulation Sources` (the `Design Sources` hierarchy remains unchanged, as only the `tb_vector_abs` module located in `Simulation Sources` was modified).
### Вкладка Libraries
### The Libraries Tab
В данной вкладке находятся файлы проекта, сгруппированные по библиотекам. В рамках данного курса, эта вкладка использоваться не будет.
This tab contains the project files grouped by library. This tab will not be used during this course.
### Вкладка Compile Order
### The Compile Order Tab
Обычно Vivado сам определяет порядок компиляции по иерархии проекта. Однако, в некоторых ситуациях он может определить что-то неправильно. На данной вкладке вы можете исправить порядок компиляции (скорее всего, вам может потребоваться эта вкладка, для указания порядка компиляции пакетов SystemVerilog).
Vivado normally determines the compilation order from the project hierarchy. However, in some situations it may determine the order incorrectly. This tab allows you to correct the compilation order (most likely you will need this tab to specify the compilation order for SystemVerilog packages).
## Дополнительные материалы
## Additional Resources
Более подробную информацию по окну `Sources` вы можете найти в руководстве пользователя Vivado: ["Vivado Design Suite User Guide: Using the Vivado IDE (UG893)"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide) (раздел ["Using the Sources Window"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide/Using-the-Sources-Window)).
More detailed information about the `Sources` window can be found in the Vivado user guide: ["Vivado Design Suite User Guide: Using the Vivado IDE (UG893)"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide) (section ["Using the Sources Window"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide/Using-the-Sources-Window)).

72
Vivado Basics/04. Simulation.md
View File

@@ -1,72 +1,72 @@
# Как запустить симуляцию в Vivado
# How to Run a Simulation in Vivado
Симуляция — это один из видов моделирования. Моделирование используется для проверки поведения разработанного устройства. Для этого, на входы модуля подаются тестовые воздействия, а с его выходов считывается результат. Параллельно этому процессу, те же самые тестовые воздействия отправляются и в эталонную модель устройства. Результат модели сверяют с результатом проектируемого устройства и, в случае расхождения, сигнализируют об ошибке.
Simulation is one form of modeling. Modeling is used to verify the behavior of a designed device. To do this, test stimuli are applied to the module inputs and the results are read from its outputs. In parallel, the same test stimuli are also applied to a reference model of the device. The model's output is compared with the output of the design under test, and any discrepancy is reported as an error.
Генерация тестовых воздействий, подача их на верифицируемое устройство и модель, сверка результатов и логирование ошибок — все это выполняется средствами верификационного окружения, которое в рамках данных лабораторных работ будет именоваться как "тестбенч". Тестбенчи — это несинтезируемые модули, поэтому они не должны находиться в папке `Design Sources`, вместо этого для них есть папка `Simulation Sources` (см. ["Менеджер проекта"](03.%20Project%20manager.md)).
Generating test stimuli, applying them to the device under verification and the reference model, comparing results, and logging errors — all of this is handled by the verification environment, referred to in these lab assignments as a "testbench". Testbenches are non-synthesizable modules and therefore must not be placed in the `Design Sources` folder; instead, the `Simulation Sources` folder is used for them (see ["Project Manager"](03.%20Project%20manager.md)).
Для каждого верифицируемого модуля в репозитории есть отдельный тестбенч. Перед запуском моделирования, необходимо убедиться, что в качестве модуля верхнего уровня в папке `Simulation Sources` выбран тестбенч того модуля, который вы собираетесь верифицировать.
A separate testbench is provided in the repository for each module to be verified. Before launching a simulation, make sure that the testbench for the module you intend to verify is selected as the top-level module in the `Simulation Sources` folder.
Есть несколько способов запустить симуляцию, рассмотрим два из них:
There are several ways to launch a simulation; two of them are described here:
1. На панели слева, в разделе `SIMULATION`, нажать `Run Simulation` → `Run Behavioral Simulation`.
1. In the left panel, under the `SIMULATION` section, click `Run Simulation` → `Run Behavioral Simulation`.
![../.pic/Vivado%20Basics/04.%20Simulation/fig_01.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_01.png)
_Рисунок 1. Запуск симуляции через вкладку `SIMULATION` окна `Flow Navigator`._
_Figure 1. Launching a simulation via the `SIMULATION` tab of the `Flow Navigator`._
2. В иерархии проекта нажать по папке `sim_1` правой кнопкой мыши, далее выбрать `Run Simulation` → `Run Behavioral Simulation`.
2. In the project hierarchy, right-click the `sim_1` folder and select `Run Simulation` → `Run Behavioral Simulation`.
![../.pic/Vivado%20Basics/04.%20Simulation/fig_02.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_02.png)
_Рисунок 2. Запуск симуляции через контекстное меню папки `sim_1` в `Simulation Sources`._
_Figure 2. Launching a simulation via the context menu of the `sim_1` folder in `Simulation Sources`._
После запуска симуляции будет промоделировано определенное количество времени, задаваемое через настройки проекта (после создания проекта мы сделали это количество равное одной секунде), после чего моделирование приостанавливается. Моделирование может быть остановлено досрочно самим тестбенчем.
After the simulation is launched, a specified amount of simulation time will be modeled — this duration is set in the project settings (we set it to one second when creating the project) — after which the simulation pauses. The simulation can also be stopped early by the testbench itself.
## Окна для работы с симуляцией
## Simulation Windows
После запуска симуляции в основной части окна Vivado откроется окно симуляции, представленное на _рис. 3_.
After the simulation is launched, the simulation window shown in _Fig. 3_ will open in the main area of the Vivado window.
![../.pic/Vivado%20Basics/04.%20Simulation/fig_03.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_03.png)
_Рисунок 3. Окно симуляции._
_Figure 3. Simulation window._
Данное окно состоит из 4-х под-окон:
This window consists of four sub-windows:
1. окно с вкладками `Scope` и `Sources`;
2. окно с вкладками `Objects` и `Protocol Instances`;
3. окно редактора с открытыми файлами и появившимся там окном временной диаграммы (которая также представляет собой файл);
4. Окно c вкладками `Tcl Console`, `Messages` и `Log`.
1. A window with the `Scope` and `Sources` tabs;
2. A window with the `Objects` and `Protocol Instances` tabs;
3. The editor window with open files and a waveform viewer (which is also represented as a file);
4. A window with the `Tcl Console`, `Messages`, and `Log` tabs.
## Окно с вкладками Scope и Sources
## The Scope and Sources Window
Вкладка Sources является той же самой вкладкой, что использовалась вами при добавлении и описании исходников и подробно разобрана в главе "[Менеджер проекта](./03.%20Project%20manager.md)".
The `Sources` tab is the same tab used when adding and describing source files, and is described in detail in the chapter "[Project Manager](./03.%20Project%20manager.md)".
Вкладка Scope отображает область видимости симуляции, верхним уровнем в которой является модуль верхнего уровня `Simulation Sources` и библиотека `glbl`, которую в рамках данного курса можно будет игнорировать. Раскрыв модуль верхнего уровня, можно увидеть иерархию модулей подобную иерархии в `Simulation Sources`. Выбрав конкретный модуль во вкладке `Scope`, можно "отправить" его на временную диаграмму: либо перетащив его в область сигналов, либо нажав по нему правой кнопкой мыши, и выбрав `Add to Wave Window`. В этом случае, на временную диаграмму добавятся входы и выходы этого модуля, а также его внутренние сигналы. Кроме того, выбор модуля во вкладке `Scope` влияет на отображение содержимого окна с вкладкой `Objects`.
The `Scope` tab displays the simulation scope. The top level consists of the top-level module from `Simulation Sources` and the `glbl` library, which can be ignored in this course. Expanding the top-level module reveals a module hierarchy similar to the one in `Simulation Sources`. Selecting a specific module in the `Scope` tab allows you to add it to the waveform viewer — either by dragging it into the signal area or by right-clicking it and selecting `Add to Wave Window`. In this case, the module's inputs, outputs, and internal signals will all be added to the waveform. In addition, selecting a module in the `Scope` tab updates the content displayed in the `Objects` tab.
На вкладке `Objects` находятся все объекты, содержащиеся в модуле, выбранном во вкладке `Scope`: его входы и выходы, внутренние провода и регистры, параметры этого модуля и т.п. С помощью данной вкладки можно добавлять отдельные объекты выбранного модуля.
The `Objects` tab lists all objects contained in the module selected in the `Scope` tab: its inputs and outputs, internal wires and registers, module parameters, and so on. This tab can be used to add individual objects of the selected module to the waveform.
## Панель инструментов симуляции
## Simulation Toolbar
После запуска симуляции, вверху окна Vivado меняется панель инструментов. На _рис. 3_ обозначены следующие кнопки:
After the simulation is launched, the toolbar at the top of the Vivado window changes. The buttons shown in _Fig. 3_ are:
1. сбросить симуляцию (горячая клавиша `Ctrl+Shift+F5`);
2. запустить симуляцию до тех пор, пока она не будет остановлена тестбенчем или вручную (горячая клавиша `F3`);
3. запустить симуляцию на указанный справа от кнопки промежуток времени (горячая клавиша `Shift+F2`);
4. перезапустить симуляцию (по умолчанию горячей клавиши нет, но может быть добавлена в настройках);
5. закрыть симуляцию.
1. Restart simulation (keyboard shortcut `Ctrl+Shift+F5`);
2. Run simulation until stopped by the testbench or manually (keyboard shortcut `F3`);
3. Run simulation for the time interval specified to the right of the button (keyboard shortcut `Shift+F2`);
4. Relaunch simulation (no default keyboard shortcut, but one can be assigned in the settings);
5. Close simulation.
Отличие сброса симуляции от её перезапуска заключается в следующем. При сбросе симуляции очищаются промоделированные значения добавленных на временную диаграмму сигналов (сами сигналы остаются на месте), при этом время симуляции перемещается на нулевую отметку (т.е симуляция начнется заново). Подобное действие может быть необходимо в случае отладки, или же если посреди моделирования вы добавили на временную диаграмму новые сигналы, и хотите увидеть их поведение с самого начала симуляции. При сбросе симуляции не выполняется компиляция исходников (даже если их содержимое было изменено).
The difference between restarting and relaunching the simulation is as follows. When the simulation is restarted, the simulated values of all signals added to the waveform are cleared (the signals themselves remain), and the simulation time is reset to zero (i.e., the simulation starts over). This may be necessary during debugging, or when you have added new signals to the waveform in the middle of a simulation and want to see their behavior from the beginning. Restarting does not recompile the source files, even if their contents have been changed.
Перезапуск симуляции похож на закрытие симуляции и повторное её открытие. При этом, если в исходниках происходили изменения — файлы будут перекомпилированы. Обратите внимание, что Vivado в первую очередь обнаруживает только изменения, сделанные из собственного редактора. В случае, если файлы были изменены извне (в особенности это касается `mem`-файлов, которые начинают использоваться с четвертой лабораторной работы) — Vivado может не обнаружить новых изменений. В случае, если симуляция ранее уже запускалась и с тех пор Vivado не обнаружил изменений в файлах — повторная компиляция не производится, и симуляция запускается средствами уже скомпилированных объектов. В случае, если изменения были сделаны извне, но Vivado их не обнаружил, можно очистить предыдущую сборку, нажав правой кнопкой мыши по `Simulation` в окне `Flow Navigator` и выбрав `Reset Behavioral Simulation` (см. _рис. 4_).
Relaunching the simulation is similar to closing and reopening it. If source files have been changed, they will be recompiled. Note that Vivado primarily detects only changes made through its own editor. If files were modified externally (this is especially relevant for `mem` files, which start being used from the fourth lab assignment), Vivado may not detect the new changes. If the simulation was previously launched and Vivado has not detected any changes in the files since then, the sources are not recompiled and the simulation runs using the previously compiled objects. If changes were made externally but Vivado did not detect them, you can clear the previous build by right-clicking `Simulation` in the `Flow Navigator` and selecting `Reset Behavioral Simulation` (see _Fig. 4_).
![../.pic/Vivado%20Basics/04.%20Simulation/fig_04.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_04.png)
_Рисунок 4. Сброс файлов симуляции._
_Figure 4. Resetting simulation files._
Таким образом, в случае если вы добавили сигналы на временную диаграмму, и хотите увидеть их поведение с нулевого момента времени, или же вы хотите очистить лог сообщений и увидеть сообщения только до определенного момента (т.е. все действия, которые не связаны с повторной компиляцией исходных кодов), имеет смысл сбросить симуляцию и выполнить моделирование повторно.
Therefore, if you have added signals to the waveform and want to see their behavior from time zero, or if you want to clear the message log and see only the messages up to a certain point (i.e., perform any action that does not involve recompiling source files), it makes sense to restart the simulation and run it again.
В случае, если вы изменили исходный код какого-то из модулей, и хотите выполнить моделирование обновленного кода, симуляцию можно закрыть и запустить повторно теми же способами, которыми вы запустили её в прошлый раз, либо перезапустить симуляцию в с помощью кнопки `4`, представленной на _рис. 3_.
If you have modified the source code of a module and want to simulate the updated code, you can close the simulation and relaunch it using the same methods as before, or relaunch it using button `4` shown in _Fig. 3_.
> Если вы изменили модуль верхнего уровня в `Simulation Sources`, вам необходимо закрыть текущую симуляцию. Без этого новая не сможет запуститься и будет выдавать ошибку "boost filesystem remove: Процесс не может получить доступ к файлу". Подробнее об этой ошибке рассказано можно прочесть в "[Списке типичных ошибок в Vivado](../Other/FAQ.md)".
> If you have changed the top-level module in `Simulation Sources`, you must close the current simulation first. Without doing so, a new simulation cannot start and will produce the error "boost filesystem remove: The process cannot access the file". More information about this error can be found in the "[List of Common Vivado Errors](../Other/FAQ.md)".
Подробнее о поиске ошибок и работе с временной диаграммой рассказано в главе "[Руководство по поиску функциональных ошибок](05.%20Bug%20hunting.md)".
More information about debugging and working with the waveform viewer is provided in the chapter "[Guide to Finding Functional Errors](05.%20Bug%20hunting.md)".

322
Vivado Basics/05. Bug hunting.md
View File

@@ -1,103 +1,105 @@
# Руководство по поиску функциональных ошибок
# Functional Bug Hunting Guide
## Цель
## Goal
При выполнении лабораторных работ вы непременно будете сталкиваться с множеством ошибок. И это нормально: **"Не ошибается тот, кто ничего не делает" — © Джейсон Стейтем**.
When completing lab assignments, you will inevitably encounter many bugs. This is perfectly normal: **"Only those who do nothing make no mistakes" — © Jason Statham**.
Важно воспитать в себе положительное восприятие обнаружения ошибок (ведь это приводит к улучшению вашего творения). Если относиться к обнаружению ошибок отрицательно, то вы подсознательно будете пытаться найти ошибки спустя рукава, но, если вы "в домике", и ошибок не видите — это не значит, что их нет.
It is important to develop a positive attitude toward finding bugs (since discovering them leads to improvements in your design). If you approach bug detection negatively, you will subconsciously try to find bugs half-heartedly — but not seeing bugs does not mean they are not there.
При должном отношении, поиск ошибок может превратиться в увлекательное детективное расследование, где у вас есть "место преступления" (обнаруженное несоответствие в поведении, обычно это не сама ошибка, а ее следствие, круги на воде) и какой-то "набор улик" (фрагменты лога, исходный код). И вы, по чуть-чуть, будете разматывать "нераспутываемую паутину лжи", получая всё новые улики, ведущие к истинной ошибке.
With the right mindset, debugging can turn into an exciting detective investigation, where you have a "crime scene" (an observed behavioral discrepancy — usually not the bug itself, but its consequence, ripples on the water) and a "set of clues" (log fragments, source code). Step by step, you will unravel what seems like an impenetrable web, uncovering new clues leading to the true root cause.
Этот документ представляет собой практикум по поиску подобных ошибок в **SystemVerilog**-коде.
This document is a hands-on guide to finding such bugs in **SystemVerilog** code.
> [!IMPORTANT]
> Обратите внимание на то, как ставится ударение в словосочетании "временна́я диаграмма" (не "вре́менная"). В обиходе это словосочетание заменяется словом "времянка".
> Note: throughout this guide, the term "waveform" refers to the signal timeline display in the Vivado simulator.
- [Руководство по поиску функциональных ошибок](#Руководство-по-поиску-функциональных-ошибок)
- [Цель](#Цель)
- [Алгоритм поиска ошибок](#Алгоритм-поиска-ошибок)
- [Работа с логом при появлении ошибок](#Работа-с-логом-при-появлении-ошибок)
- [Поиск ошибки на временной диаграмме](#Поиск-ошибки-на-временной-диаграмме)
- [Открытие файла исходного кода проблемного сигнала](#Открытие-файла-исходного-кода-проблемного-сигнала)
- [Добавление сигналов объектов на временную диаграмму](#Добавление-сигналов-объектов-на-временную-диаграмму)
- [Сброс симуляции и ее повтор, установка времени моделирования](#Сброс-симуляции-и-ее-повтор-установка-времени-моделирования)
- [Исправление сигналов с Z-состоянием](#Исправление-сигналов-с-z-состоянием)
- [Поиск ошибки в сигналах, формирующих проблемный сигнал](#Поиск-ошибки-в-сигналах-формирующих-проблемный-сигнал)
- [Исправление логики проблемного сигнала](#Исправление-логики-проблемного-сигнала)
- [Проблема необъявленных сигналов](#Проблема-необъявленных-сигналов)
- [Самостоятельная работа](#Самостоятельная-работа)
- [Functional Bug Hunting Guide](#functional-bug-hunting-guide)
- [Goal](#goal)
- [Bug Hunting Algorithm](#bug-hunting-algorithm)
- [Working with the Log When Errors Appear](#working-with-the-log-when-errors-appear)
- [Locating the Bug on the Waveform](#locating-the-bug-on-the-waveform)
- [Opening the Source File of the Problematic Signal](#opening-the-source-file-of-the-problematic-signal)
- [Adding Object Signals to the Waveform](#adding-object-signals-to-the-waveform)
- [Restarting the Simulation and Setting Simulation Time](#restarting-the-simulation-and-setting-simulation-time)
- [Fixing Signals in the Z-State](#fixing-signals-in-the-z-state)
- [Tracing the Bug Through the Signals Driving the Problematic Signal](#tracing-the-bug-through-the-signals-driving-the-problematic-signal)
- [Fixing the Logic of the Problematic Signal](#fixing-the-logic-of-the-problematic-signal)
- [The Problem of Undeclared Signals](#the-problem-of-undeclared-signals)
- [Independent Exercise](#independent-exercise)
## Алгоритм поиска ошибок
## Bug Hunting Algorithm
1. Обычно всё начинается с сообщения в логе тестов (никто не проверяет глазами временную диаграмму сложных проектов, состоящую из тысяч сигналов, меняющихся миллионы раз за микросекунду), но на наших лабораторных работах с относительно простыми модулями, этот шаг иногда может быть и пропущен.
Сообщение в логе обычно содержит следующую ключевую информацию: имя сигнала, на котором установилось неверное значение, и время, когда это произошло. Чем лучше написано верификационное окружение, тем больше ключевой информации будет отражено в сообщении, поэтому его написание является своего рода искусством.
2. Получив имя сигнала и время, мы отправляемся на временную диаграмму и проверяем нашу ошибку. Как это сделать? Необходимо определить по коду, какие сигналы и каким образом управляют нашим сигналом. Вариантов может быть несколько:
1. Управляющие сигналы имеют корректное значение, но логика, по которой они управляют сигналом неверна, из-за этого на нем возникает неверное значение.
Это идеальный случай, при возникновении которого мы сразу же находим причину проблемы и исправляем ее.
2. Логика управления верна, а какая-то часть управляющих сигналов имеет неверное значение (пусть для примера, неверное значение будет на управляющем сигнале `X`). Это означает, что обнаруженное несоответствие сигналов является уже следствием какой-то ошибки, и мы должны вернуться к шагу 2, проверяя источники для сигнала со значением `X`. Так происходит до тех пор, пока мы не попадаем в тип 1.
3. Логика управления и значения управляющих сигналов верны. Это самый сложный тип ошибок, который заключается либо в ошибке в спецификации разрабатываемого устройства, либо в САПРе или компонентах, влияющих на его работу. В рамках данного курса вас не должны заботить данные ошибки, и при их возникновении вам стоит обратиться к преподавателю (предварительно убедившись, что ошибка совершенно точно не подходит под первые два варианта).
4. Любая возможная комбинация всех предыдущих типов.
3. Обнаружив первопричину ошибки, мы исправляем ее (возможно дополняя набор тестов, или внеся правки в спецификацию), и повторно запускаем все тесты, чтобы убедиться в двух вещах:
1. ошибка действительно исправлена
2. исправление ошибки не породило новых ошибок
1. The process usually starts with a message in the test log (nobody manually inspects a waveform of a complex project with thousands of signals changing millions of times per microsecond), but in our lab assignments with relatively simple modules, this step may sometimes be skipped.
The log message typically contains the following key information: the name of the signal that received an incorrect value, and the time at which this occurred. The better the testbench is written, the more useful information the message will contain — writing a good testbench is something of an art.
Давайте отработаем эти шаги на примере отладки ошибок в [проекте](./vector_abs/) по вычислению приблизительной длины вектора, создание которого было описано в документе "[Менеджер проекта](./03.%20Project%20manager.md)".
2. Having the signal name and timestamp, we go to the waveform and investigate the error. How do we do this? We need to determine from the code which signals drive our signal of interest and how. There are several possibilities:
1. The driving signals have correct values, but the logic by which they drive the target signal is wrong, causing it to receive an incorrect value.
This is the ideal case — we immediately identify the root cause and fix it.
2. The driving logic is correct, but one or more of the driving signals has an incorrect value (let's call that signal `X`). This means the observed discrepancy is a symptom of some other error, and we must return to step 2, now investigating the sources of signal `X`. This repeats until we reach case 1.
3. Both the driving logic and the values of the driving signals are correct. This is the most complex type of error — it implies either a bug in the specification of the device being developed, or a problem in the EDA tool or its components. In the context of this course, you should not be concerned about such errors; if they arise, consult your instructor (after confirming that the error definitely does not fall under cases 1 or 2).
4. Any combination of the above.
## Работа с логом при появлении ошибок
3. Once the root cause is identified, we fix it (possibly extending the test suite or revising the specification) and rerun all tests to verify two things:
1. The bug is actually fixed.
2. The fix did not introduce new bugs.
После запуска симуляции мы видим в логе множество ошибок:
Let us practice these steps by debugging errors in the [project](./vector_abs/) that computes the approximate magnitude of a vector, as described in the "[Project Manager](./03.%20Project%20manager.md)" document.
## Working with the Log When Errors Appear
After running the simulation, we see multiple errors in the log:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_01.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_01.png)
_Рисунок 1. Пример сообщения об ошибках в тесте._
_Figure 1. Example of test error messages._
В любой ситуации с множеством ошибок, сначала надо разбираться с самой первой из них, поскольку она может быть причиной появления всех остальных. Поэтому листаем лог до момента первой ошибки:
When faced with many errors, always start with the very first one, since it may be the cause of all the others. Scroll the log to find the first error:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_02.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_02.png)
_Рисунок 2. Пример конкретной ошибки в тесте._
_Figure 2. Example of a specific test error._
В логе сказано, что в момент времени `5ns`, на вход схемы подавались координаты вектора, равные `0` и `0`, модель посчитала, что длина вектора равна нулю, в то время как схема вернула значение `x`.
The log states that at time `5ns`, the circuit received vector coordinates of `0` and `0`, the reference model computed a vector magnitude of zero, while the circuit returned `x`.
## Поиск ошибки на временной диаграмме
## Locating the Bug on the Waveform
Давайте найдем это место на временной диаграмме. Обычно, сразу после запуска симуляции на временной диаграмме отображено место, где симуляция остановилась (возможно с очень неподходящим масштабом). Для начала подгоним масштаб таким образом, чтобы вся временная диаграмма умещалась в окне. Это делается либо нажатием правой кнопкой мыши по области отображения сигналов, с выбором "Full View" во всплывающем меню, либо нажатием соответствующей кнопки на панели временной диаграммы (см. _рис. 4_), либо нажатием комбинации клавиш `Ctrl+0`. Затем найдем приблизительное место рядом с тем временем, что нас интересует, установим там курсор, и приблизим масштаб (покрутив колесиком мыши при зажатой клавише `Ctrl`), периодически уточняя местоположения курсора, пока не найдем интересующее нас место.
Let us find this location on the waveform. Immediately after a simulation run, the waveform typically shows the point where the simulation stopped (possibly at an inconvenient zoom level). First, adjust the zoom so that the entire waveform fits in the window. This can be done by right-clicking in the signal display area and selecting "Full View", by clicking the corresponding button on the waveform toolbar (see _Fig. 4_), or by pressing `Ctrl+0`. Then find the approximate location near the time of interest, place the cursor there, and zoom in (scroll with the mouse wheel while holding `Ctrl`), periodically adjusting the cursor position until you reach the location of interest.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_03.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_03.png)
_Рисунок 3. Пример временной диаграммы сразу поле остановки моделирования._
_Figure 3. Example of the waveform immediately after the simulation stops._
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_04.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_04.png)
_Рисунок 4. Пример установки масштаба временной диаграммы таким образом, чтобы та помещалась в текущем окне._
_Figure 4. Example of fitting the entire waveform into the current window._
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_05.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_05.png)
_Рисунок 5. Пример временной диаграммы после подгонки масштаба._
_Figure 5. Example of the waveform after adjusting the zoom._
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_06.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_06.png)
_Рисунок 6. Установка курсора в начало моделирования, чтобы, при увеличении масштаба, временная диаграмма сходилась к началу._
_Figure 6. Placing the cursor at the start of simulation so that zooming in converges toward the beginning._
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_07.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_07.png)
_Рисунок 7. Временная диаграмма, отмасштабированная к времени ошибки с рис. 2._
_Figure 7. Waveform zoomed in to the error time from Fig. 2._
Мы видим ровно ту информацию, которую нам предоставил тестбенч. Теперь надо разобраться в причинах возникновения X-состояния. Такое может произойти по множеству причин, вот три из них:
We see exactly the information the testbench reported. Now we need to determine what is causing the X-state. This can happen for several reasons, including:
1. какой-то из сигналов, формирующих этот находится в `X` или `Z` состоянии;
2. два каких-то сигнала одновременно пытаются выставить разные значения на целевой сигнал;
3. этот сигнал является выходом модуля, но был описан с ключевым словом `input`.
1. One of the signals driving this signal is in the `X` or `Z` state.
2. Two signals are simultaneously trying to drive the target signal to different values.
3. This signal is a module output but was declared with the `input` keyword.
## Открытие файла исходного кода проблемного сигнала
## Opening the Source File of the Problematic Signal
В любом случае, первым делом необходимо определить, источник формирования значения сигнала `res`. Откроем файл с исходным кодом, где определен данный сигнал. Для этого, нажмем правой кнопкой мыши по имени сигнала на временной диаграмме, и выберем `Go To Source Code`:
In any case, the first step is to identify the source that drives the value of signal `res`. Open the source file where this signal is defined. To do so, right-click the signal name in the waveform and select `Go To Source Code`:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_08.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_08.png)
_Рисунок 8. Переход к месту объявления "проблемного" сигнала._
_Figure 8. Navigating to the declaration of the "problematic" signal._
Откроется код, представленный в _листинге 1_ (с курсором на строчке `logic [31:0] res;`):
The code shown in _Listing 1_ will open (with the cursor on the line `logic [31:0] res;`):
```Verilog
module tb_vector_abs();
@@ -114,97 +116,97 @@ vector_abs dut(
//...
```
_Листинг 1. Начало кода симулируемого тестбенча._
_Listing 1. Beginning of the simulated testbench code._
Выделив `res` мы видим, что у нас подсветился `res` в строке `abs(res)`. Это означает, что мы завели наш провод внутрь объекта `dut` модуля `vector_abs`, и у нас проблема второго типа (в логике работы провода `res` нет ошибок, он принял некорректное значение, поскольку ему таковое передали).
Selecting `res`, we see it is also highlighted in the line `abs(res)`. This means we connected our wire into the `dut` instance of module `vector_abs`, and the problem is of the second type (there is no error in the logic of wire `res` itself — it received an incorrect value because that value was passed to it from the inside).
В этом можно убедиться, если вытащить сигналы модуля `vector_abs` на временную диаграмму. Чтобы это сделать, надо переключиться на окно `Scope`, где размещена иерархия моделируемых объектов.
This can be confirmed by pulling the signals of module `vector_abs` onto the waveform. To do this, switch to the `Scope` window, which shows the hierarchy of simulated objects.
## Добавление сигналов объектов на временную диаграмму
## Adding Object Signals to the Waveform
> [!IMPORTANT]
> Обратите внимание, что в иерархии окна `Scope` находятся не имена модулей, а имена сущностей модуля. В приведенном выше листинге кода мы создали сущность модуля `vector_abs` с именем `dut`, поэтому в иерархии `Scope` мы видим внутри модуля верхнего уровня объект `dut` (не `vector_abs`), так будет и со всеми вложенными объектами.
> Note that the `Scope` window hierarchy shows instance names, not module type names. In the code listing above, we created an instance of module `vector_abs` named `dut`, so inside the top-level module we see the object `dut` (not `vector_abs`) in the `Scope` hierarchy. The same applies to all nested instances.
Выделим объект `dut`. В окне `Objects` справа отобразятся все внутренние сигналы (входы/выходы, внутренние провода и регистры) объекта `dut`:
Select the `dut` object. The `Objects` window on the right will display all internal signals (ports, internal wires, and registers) of the `dut` instance:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_09.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_09.png)
_Рисунок 9. Отображение внутренних сигналов проверяемого модуля._
_Figure 9. Displaying the internal signals of the module under test._
Вообще говоря, мы уже видим, что выход `abs` (к которому подключен наш провод `res`) находится в X-состоянии, но для отработки навыков, разберемся с добавлением новых сигналов на временную диаграмму. Можно поступить двумя способами:
We can already see that the `abs` output (which is connected to our wire `res`) is in the X-state, but for the sake of practice, let us walk through how to add new signals to the waveform. There are two ways:
1. Добавить все сигналы (то, что видно в окне `Objects` на временную диаграмму) из окна `Scope` для этого, либо перетаскиваем нужный нам объект, зажав левую кнопку мыши на временную диаграмму, либо жмем правой кнопкой мыши по нужному объекту, и выбираем `Add to Wave Window`
2. Добавить отдельные сигналы из окна `Objects`. Для этого выделяем их (возможно множественное выделение через модификаторы `shift` или `ctrl`), и как и в прошлом случае, либо перетаскиваем сигналы левой кнопкой мыши, либо добавляем их через правую кнопку мыши.
1. Add all signals visible in the `Objects` window from the `Scope` window: either drag the desired instance onto the waveform while holding the left mouse button, or right-click the instance and select `Add to Wave Window`.
2. Add individual signals from the `Objects` window: select them (multiple selection via `Shift` or `Ctrl` modifiers), then either drag them onto the waveform or add them via right-click.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_10.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_10.png)
_Рисунок 10. Добавление сигналов модуля на временную диаграмму._
_Figure 10. Adding module signals to the waveform._
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_11.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_11.png)
_Рисунок 11. Результат добавления сигналов модуля на временную диаграмму._
_Figure 11. Result of adding module signals to the waveform._
По мере роста сложности проекта, число сигналов на временной диаграмме будет постоянно расти, в связи с чем встает вопрос группировки сигналов.
As a project grows in complexity, the number of signals on the waveform increases, which makes signal grouping important.
Для того чтобы объединить сигналы в группу, необходимо их выделить. Это можно сделать двумя способами:
To group signals together, first select them. This can be done in two ways:
1. кликнув левой кнопкой мыши по каждому из интересующих сигналов при зажатой клавише `Ctrl`;
2. если речь идет о диапазоне сигналов, можно выбрать сигнал с одного края, после чего, при зажатой клавише `Shift`, выбрать сигнал с другого края этого диапазона.
1. Left-click each signal of interest while holding `Ctrl`.
2. For a range of signals, click the signal at one end, then hold `Shift` and click the signal at the other end of the range.
После выбора, необходимо нажать правой кнопкой мыши по выделенным сигналам, и в низу выпадающего списка выбрать `New Group`.
After selecting, right-click the highlighted signals and choose `New Group` from the bottom of the context menu.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_12.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_12.png)
_Рисунок 12. Пример создания группы сигналов (контекстное меню было обрезано для удобства отображения)._
_Figure 12. Example of creating a signal group (the context menu has been cropped for clarity)._
После создания группы, ей нужно будет дать имя. В случае, если все сигналы принадлежат одному модулю, удобно называть группу сигналов именем этого модуля.
After creating the group, assign it a name. When all signals belong to the same module, it is convenient to name the group after that module.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_13.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_13.png)
_Рисунок 13. Пример созданной группы сигналов._
_Figure 13. Example of a created signal group._
Данную группу можно сворачивать и разворачивать, нажимая на соответствующую стрелку слева от имени группы.
The group can be collapsed and expanded by clicking the corresponding arrow to the left of the group name.
> [!IMPORTANT]
> Обратите внимание, что часть сигналов отображают какое-то значение (сигнал `abs` отображает X-состояние), а часть не отображают ничего. Так произошло, потому что провод `abs` **непрерывно связан** с проводом `res`. С точки зрения симулятора это одна сущность, и записывая во время моделирования значения для сигнала `res`, он неявно записывал значения и для сигнала `abs`. Этого нельзя сказать про остальные сигналы, которых не было во время моделирования на временной диаграмме.
> Notice that some signals display a value (the `abs` signal shows an X-state) while others show nothing. This is because wire `abs` is **continuously connected** to wire `res`. From the simulator's perspective, they are the same entity, and when the simulator recorded values for `res` during simulation, it implicitly recorded them for `abs` as well. This does not apply to the other signals that were not present on the waveform during the simulation run.
## Сброс симуляции и ее повтор, установка времени моделирования
## Restarting the Simulation and Setting Simulation Time
Для того, чтобы получить отсутствующие значения, необходимо повторить моделирование. Для этого, необходимо сбросить время моделирования в 0 и запустить его снова.
To obtain the missing values of the newly added signals, we need to repeat the simulation. To do so, reset the simulation time to 0 and run it again.
Для этого, необходимо на панели симуляции нажать кнопку `Restart` (`|◀`), а затем кнопку `Run all` (`▶`) или `Run for` (`▶t`). Положение кнопок в окне Vivado иллюстрирует _рис. 14_.
Click the `Restart` button (`|◀`) on the simulation toolbar, then click `Run all` (`▶`) or `Run for` (`▶t`). The button positions in the Vivado window are shown in _Fig. 14_.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_14.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_14.png)
_Рисунок 14. Расположение кнопок, управляющих моделированием в окне Vivado._
_Figure 14. Location of the simulation control buttons in the Vivado window._
Панель управления симуляции с кнопками:
Simulation control toolbar buttons:
1. `Restart`, горячие клавиши: `Ctrl+Shift+F5`;
2. `Run all`, горячая клавиша: `F3`;
3. `Run for`, горячие клавиши: `Shift+F2`;
1. `Restart`, keyboard shortcut: `Ctrl+Shift+F5`;
2. `Run all`, keyboard shortcut: `F3`;
3. `Run for`, keyboard shortcut: `Shift+F2`;
4. `Relaunch Simulation`.
`Run for` выполняет моделирование указанного количества времени, после чего моделирование приостанавливается. Моделирование может быть остановлено так же и вручную, либо вызовом соответствующей инструкции из кода теста.
`Run for` runs the simulation for the specified amount of time, after which the simulation pauses. The simulation can also be stopped manually or by calling the appropriate instruction from the test code.
`Run all` отличается от `Run for` тем, что в качестве количества моделируемого времени указывается "бесконечность", и моделирование будет остановлено только вручную, либо вызовом соответствующей инструкции.
`Run all` differs from `Run for` in that it runs indefinitely and stops only when manually interrupted or when the appropriate instruction is called from the test code.
> [!IMPORTANT]
> Обратите внимание, что для добавления недостающих значений добавленных сигналов лучше всего выполнять описанную выше инструкцию. Аналогичного результата можно добиться и нажатием на кнопку `Relaunch Simulation`, однако эта команда работает дольше и, если вы не меняли исходный код модулей, не нужна.
> To populate the missing values for newly added signals, it is best to follow the procedure described above. A similar result can be achieved by clicking `Relaunch Simulation`, but this command takes longer and is unnecessary if you have not modified any source files.
Кроме того, чтобы курсор и лог снова не ушли далеко от места первой ошибки, можно сразу указать, необходимое нам время моделирования перед выполнением команды `Run for`: `5ns`.
Additionally, to prevent the cursor and log from jumping far away from the first error, you can specify the desired simulation time before clicking `Run for`: `5ns`.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_15.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_15.png)
_Рисунок 15. Пример моделирования 5ns._
_Figure 15. Example of simulating 5 ns._
На _рис. 16_ представлен результат моделирования с новыми сигналами.
_Fig. 16_ shows the simulation result with the new signals.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_16.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_16.png)
_Рисунок 16. Результат повторного моделирования после добавления на временную диаграмму новых сигналов._
_Figure 16. Result of re-running the simulation after adding new signals to the waveform._
Видим два сигнала в Z-состоянии и один сигнал в X-состоянии. Обычно, сигналы с Z-состоянием проще всего исправить, т.к. зачастую это забытое или некорректное подключение провода. Кроме того, сигнал, зависящий от сигнала с Z-состоянием, может оказаться в X-состоянии, так что это может быть решением нашей проблемы, поэтому проверим провода `min` и `min_half`. Сперва займемся сигналом `min` и перейдем к шагу 2 нашего алгоритма (нажимаем правой кнопкой мыши и выбираем `Go To Source Code`):
We see two signals in the Z-state and one signal in the X-state. Signals in the Z-state are usually the easiest to fix, as they typically indicate a forgotten or incorrect wire connection. Furthermore, a signal that depends on a Z-state signal may itself end up in an X-state — so fixing the Z-state issue might resolve our problem. Let us inspect wires `min` and `min_half`. Start with `min` and go to step 2 of our algorithm (right-click and select `Go To Source Code`):
```Verilog
module vector_abs(
@@ -226,105 +228,105 @@ module vector_abs(
//...
```
## Исправление сигналов с Z-состоянием
## Fixing Signals in the Z-State
Мы видим, что сигнал `min` подключен к выходу `min` объекта `max_min_unit` модуля `max_min`. Добавим сигналы этого модуля на временную диаграмму. Для этого, необходимо раскрыть список объектов, содержащихся в объекте `dut` иерархии объектов `Scope` и выбрать там объект `max_min_unit`.
We can see that signal `min` is connected to the `min` output of the `max_min_unit` instance of module `max_min`. Let us add the signals of this module to the waveform. To do so, expand the list of objects inside the `dut` instance in the `Scope` hierarchy and select the `max_min_unit` object.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_17.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_17.png)
_Рисунок 17. Добавление сигналов вложенных модулей на временную диаграмму._
_Figure 17. Adding signals from a submodule to the waveform._
Добавляем внутренние сигналы на временную диаграмму, группируем их под именем `max_min`, и повторяем моделирование.
Add the internal signals to the waveform, group them under the name `max_min`, and re-run the simulation.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_18.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_18.png)
_Рисунок 18. Результат добавления и группировки сигналов подмодуля `max_min`._
_Figure 18. Result of adding and grouping signals from the `max_min` submodule._
Произошло что-то странное: все внутренние сигналы объекта `max_min_unit` "зеленые" (не имеющие X или Z состояния), однако подключенный к выходу этого модуля сигнал `min` находится в Z-состоянии. Как такое могло произойти?
Something strange happened: all internal signals of the `max_min_unit` instance are "green" (no X or Z states), yet the signal `min` connected to this module's output is in the Z-state. How is that possible?
Если присмотреться к сигналу `min`, находящемуся в Z-состоянии, можно заметить, что младшая цифра находится не в Z-состоянии, а в состоянии `0`, такое же значение стоит и на сигнале `min` объекта `max_min_unit`. Это интересно.
If you look closely at the `min` signal in the Z-state, you will notice that its least significant digit is not in the Z-state but shows `0` — the same value shown by the `min` signal of the `max_min_unit` instance. Interesting.
Если присмотреться к этим двум сигналам еще пристальней, то можно увидеть, что у сигнала `min` объекта `dut` разрядность 32 бита, в то время как разрядность сигнала `min` объекта `max_min_unit` составляет 4 бита.
Looking even more closely at these two signals, you can see that the `min` signal of the `dut` instance is 32 bits wide, while the `min` signal of the `max_min_unit` instance is only 4 bits wide.
Это и является проблемой: мы подключили 4 бита 4-разрядного сигнала `min` к младшим 4 битам 32-разрядного сигнала `min`, а остальные разряды остались не подключенными.
This is the problem: we connected the 4 bits of a 4-bit `min` signal to the lower 4 bits of a 32-bit `min` signal, leaving the remaining bits unconnected.
По всей видимости, при написании модуля `max_min`, была указана неверная разрядность сигнала `min`, вместо `31` было написано `3`. Исправим это и повторим моделирование.
Apparently, when writing the `max_min` module, the width of the `min` signal was specified incorrectly: `3` was written instead of `31`. Let us fix this and re-run the simulation.
> [!IMPORTANT]
> Обратите внимание, что поскольку мы изменили исходный код, в этот раз необходимо нажать на кнопку `Relaunch Simulation`, поскольку нужна повторная компиляция проекта.
> Note that since we modified the source code, this time we must click `Relaunch Simulation` to trigger recompilation of the project.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_19.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_19.png)
_Рисунок 19. Результат моделирования после исправления разрядности сигнала `min`._
_Figure 19. Simulation result after fixing the bit-width of signal `min`._
В логе сообщается о 102 найденных ошибках. Ровно на одну ошибку меньше, чем было ранее. Это не означает, что в проекте осталось 102 ошибки, только то, что, исправив данную ошибку — мы действительно что-то исправили, и один из тестовых сценариев, который ранее завершался ошибкой, теперь завершился без неё.
The log now reports 102 errors — exactly one fewer than before. This does not mean there are 102 bugs remaining; it simply confirms that fixing this particular bug actually changed something, and one test scenario that previously failed now passes.
Помните, что если в проекте много ошибок, то часть ошибок может выправлять поведение других ошибок (хоть и не всегда, но иногда минус на минус может выдать плюс в контексте ошибок проекта), поэтому надо с осторожностью полагаться на число найденных ошибок, если это число больше нуля.
Keep in mind that when a project has many bugs, some bugs may be masking the effects of others (two wrongs can sometimes make a right in the context of bug interactions), so be cautious about relying on the error count when it is greater than zero.
Посмотрим на нашу временную диаграмму снова, и выберем дальнейшие действия:
Let us look at the waveform again and decide on the next steps:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_20.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_20.png)
_Рисунок 20. Временная диаграмма после исправления разрядности сигнала `min`._
_Figure 20. Waveform after fixing the bit-width of signal `min`._
Мы видим, что на временной диаграмме не осталось сигналов в X или Z-состоянии, а значит мы собрали все "низковисящие" улики нашего с вами расследования. Вернемся к месту преступления и попробуем поискать новые улики:
We see that no signals remain in the X or Z state, meaning we have collected all the "low-hanging fruit" in our investigation. Let us return to the scene of the crime and look for new clues:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_21.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_21.png)
_Рисунок 21. Первая ошибка в новом логе моделирования._
_Figure 21. First error in the new simulation log._
## Поиск ошибки в сигналах, формирующих проблемный сигнал
## Tracing the Bug Through the Signals Driving the Problematic Signal
Мы видим, что первой ошибкой в логе стала не та ошибка, что была прежде. Раньше первый неверный результат мы видели в момент времени `5ns`, когда на схему подавались значения `0` и `0`, теперь же первой ошибкой стал момент времени `10ns`, когда на схему подаются значения `1` и `1`. Наше устройство считает, что результат должен равняться `3`, в то время как модель считает, что результат должен равняться `1`. Проверим, нет ли ошибки в модели и посчитаем результат самостоятельно:
The first error in the log is now different from before. Previously, the first incorrect result appeared at time `5ns` with inputs `0` and `0`; now the first error occurs at `10ns` with inputs `1` and `1`. Our circuit computes the result as `3`, while the reference model says it should be `1`. Let us compute it manually to verify the model:
Для определения приблизительной длины вектора в евклидовом пространстве (т.е. длины гипотенузы прямоугольного треугольника, которая равна квадратному корню из суммы квадратов катетов) можно воспользоваться формулой:
To approximate the Euclidean magnitude of a vector (i.e., the hypotenuse of a right triangle, equal to the square root of the sum of the squares of its legs), we use the formula:
`sqrt(a^2 + b^2) ≈ max + min/2`, где `max` и `min` — большее и меньшее из пары чисел соответственно [**Ричард Лайонс: Цифровая обработка сигналов, стр. 475**].
`sqrt(a^2 + b^2) ≈ max + min/2`, where `max` and `min` are the larger and smaller of the pair, respectively [**Richard Lyons: Understanding Digital Signal Processing, p. 475**].
Подставим наши числа в формулу (поскольку оба числа равны, не важно какое из них будет максимумом, а какое минимумом):
Substituting our values (since both numbers are equal, it does not matter which is max and which is min):
```text
1 + 1/2 = 1.5
```
Ни модель, ни схема не правы?
So neither the model nor the circuit is correct?
На самом деле, наше устройство поддерживает только целочисленную арифметику, поэтому результат будет:
Actually, our device supports only integer arithmetic, so the result is:
```text
1 + 1/2 = 1 + 0 = 1
```
Модель правильно отразила особенность нашего устройства и дала корректный результат.
The model correctly accounted for this property of our device and produced the correct result.
Значит надо смотреть как формируется результат в нашем устройстве. Посмотрим на выход `abs` в модуле `vector_abs`:
So we need to look at how the result is computed inside our circuit. Let us inspect the `abs` output in module `vector_abs`:
```Verilog
assign abs = max + min_half;
```
Выход `abs` зависит от двух внутренних сигналов: `max` и `min_half`. В соответствии с нашим алгоритмом, либо проблема в логике, связывающей эти два сигнала (операции сложения), либо в значении какого-то из этих сигналов, либо комбинации этих вариантов.
The `abs` output depends on two internal signals: `max` and `min_half`. According to our algorithm, the problem is either in the logic connecting these two signals (the addition operation), in the value of one of them, or a combination of both.
Изучив модуль, мы понимаем, что в логике этого присваивания проблем нет, т.к. оно повторяет логику формулы `max + min/2`, складывая максимум с половиной минимума. Значит проблема в значении какого-то из этих сигналов (или обоих из них). Посчитаем значения этих сигналов самостоятельно (для сложного проекта эти значения посчитала бы модель):
Examining the module, we conclude that the assignment logic is correct — it implements `max + min/2` by adding the maximum to half the minimum. So the problem must be in the value of one (or both) of these signals. Let us compute the expected values ourselves (in a complex project, this would be done by the reference model):
`1` и `0`.
`1` and `0`.
Смотрим, какие значения установлены на сигналах `max` и `min_half` в момент времени `10ns`.
Now let us check the actual values of `max` and `min_half` at time `10ns`.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_22.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_22.png)
_Рисунок 22. Значения сигналов `max` и `min_half` в момент времени `10 ns` (интересующие нас сигналы выделены зелёным)_
_Figure 22. Values of signals `max` and `min_half` at time `10 ns` (signals of interest highlighted in green)_
> [!IMPORTANT]
> Обратите внимание: вы можете менять цвета сигналов временной диаграммы через контекстное меню выделенных сигналов.
> Note: you can change the colors of waveform signals through the context menu of the selected signals.
Мы видим, что в момент времени `10 ns` значения `max` и `min_half` изменились как `1 -> 4` и `2 -> 8` соответственно. Нас интересуют значения `1` и `2`, т.к. в момент времени `10ns` на выходе схемы в этот момент был установившийся результат для предыдущих значений (еще не успел посчитаться результат для новых значений).
We see that at time `10 ns`, the values of `max` and `min_half` transition as `1 -> 4` and `2 -> 8` respectively. We are interested in the values `1` and `2`, since at time `10ns` the circuit's output still holds the settled result for the previous inputs (the output for the new inputs has not yet been computed).
Значение `max=1` совпадает с ожидаемым, в то время как `min_half=2` явно нет.
The value `max=1` matches the expected value, while `min_half=2` clearly does not.
Мы нашли причину неправильного вычисления результата: и правда, `1+2=3`, теперь необходимо найти ошибку в вычислении сигнала `min_half`.
We have identified the cause of the incorrect result: indeed, `1+2=3`. Now we need to locate the bug in the computation of signal `min_half`.
Как и с сигналом `abs`, необходимо определить сигналы, влияющие на значение сигнала `min_half`. Данный сигнал подключен к выходу `quotient` модуля `half_divider`, поэтому мы будем смотреть исходный код данного модуля:
As with signal `abs`, we need to identify the signals that drive `min_half`. This signal is connected to the `quotient` output of the `half_divider` module, so let us inspect its source code:
```Verilog
module half_divider(
@@ -337,41 +339,41 @@ module half_divider(
endmodule
```
Что делает данный модуль? Он принимает на вход значение и делит его на два. На вход данного модуля будет приходить значение минимума из нашей формулы.
What does this module do? It receives a value and divides it by two. The minimum value from our formula is fed to its input.
Выход данного модуля зависит от входа `numerator` и логики сдвига влево на 1. Это значит, что проблема либо в логике, либо в значении, подаваемом на вход. Выведем сигнал `numerator` на временную диаграмму и посмотрим на его значение в момент времени `10ns.
The output of this module depends on the `numerator` input and a left-shift-by-1 operation. So the problem is either in the logic or in the value being fed to the input. Let us add the `numerator` signal to the waveform and check its value at time `10ns`.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_23.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_23.png)
_Рисунок 23. Значение сигнала `numerator` в момент времени `10 ns`._
_Figure 23. Value of signal `numerator` at time `10 ns`._
Мы помним, что в момент, когда схема начала выдавать неправильный результат, на его входы подавались числа `1` и `1`, это значит, что на вход `numerator` пришло корректное значение: минимум из этих двух чисел и правда равен `1`. Проверим логику данного модуля.
We recall that when the circuit started producing an incorrect result, the inputs were `1` and `1`, so the `numerator` received the correct value: the minimum of the two numbers is indeed `1`. Let us now check the module's logic.
## Исправление логики проблемного сигнала
## Fixing the Logic of the Problematic Signal
Операция деления в цифровой схемотехнике является очень "дорогой" в плане ресурсов логических блоков и критического пути, поэтому этой операции часто стараются избегать. В нашем случае, нам не нужно обычное деление — нам нужно деление только напополам. В двоичной арифметике, для того чтобы разделить число на два, достаточно отбросить его младшую цифру. Вы часто пользуетесь подобной операцией в повседневной жизни при выполнении операции деления на 10: отбрасываете младшую цифру в десятичной арифметике.
Division is a very "expensive" operation in digital logic in terms of resources and critical path, so it is often avoided. In our case, we do not need general-purpose division — we only need to divide by two. In binary arithmetic, dividing a number by two is equivalent to discarding its least significant bit. You routinely do the same in decimal arithmetic when dividing by 10: you simply drop the last digit.
Именно поэтому, когда мы в первый раз пытались посчитать результат "на бумаге", у нас было расхождение с моделью: когда мы делим 1 на 2, мы получаем 0.5, однако деление путем отбрасывания цифры округляет результат вниз (1/2=0, 15/10=1).
This is exactly why our first manual calculation differed from the model: dividing 1 by 2 gives 0.5, but discarding the last digit rounds the result down (1/2 = 0, 15/10 = 1).
Как "отбросить" цифру средствами цифровой логики? Для этого используется операция сдвига вправо.
How do we "discard a digit" in digital logic? We use the right-shift operation.
Операция сдвига вправо в **SystemVerilog** записывается оператором `>>`. Справа от оператора указывается число "отбрасываемых цифр", в нашем случае одна. Но постойте, в логике присваивания стоит оператор `<<`. Это ошибка, исправим ее!
The right-shift operator in **SystemVerilog** is `>>`. The number of bits to shift (i.e., digits to discard) is specified to the right of the operator — in our case, 1. But wait — the assignment currently uses the `<<` operator. That is the bug; let us fix it!
Повторяем моделирование.
Re-run the simulation.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_24.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_24.png)
_Рисунок 24. Результат моделирования после исправления оператора сдвига._
_Figure 24. Simulation result after fixing the shift operator._
Снова на одну ошибку меньше. Не унываем, вряд ли в проекте число ошибок больше, чем число непустых строк самого проекта. Возвращаемся к начальной ошибке:
One fewer error again. Do not be discouraged — the number of bugs in a project is unlikely to exceed the number of non-empty lines in the code. Let us return to the first error:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_25.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_25.png)
_Рисунок 25. Первая ошибка в повторном моделировании._
_Figure 25. First error in the re-run simulation._
Мы продвинулись во времени безошибочного моделирования до `15 ns`, начинаем наше расследование с начала:
We have now advanced the error-free simulation time to `15 ns`. Let us start our investigation from the beginning:
На вход схемы подаются значения `3` и `4`, схема считает, что результатом вычисления `max + min/2` будет `2`, модель считает, что `5`. Посчитаем сами:
Inputs `3` and `4` are applied to the circuit. The circuit thinks the result of `max + min/2` is `2`, but the model says it should be `5`. Let us compute manually:
```text
max=4
@@ -379,17 +381,17 @@ min=3
max + min/2 = 4 + 3/2 = 4 + 1 = 5
```
И снова модель выдала правильный результат. Разберемся в значениях сигналов, формирующих сигнал `abs`.
Once again, the model produced the correct result. Let us examine the values of the signals that form the `abs` output.
## Проблема необъявленных сигналов
## The Problem of Undeclared Signals
К этому моменту на вашей временной диаграмме скорей всего стало уже очень много сигналов. Уберем лишние, оставив только внутренние сигналы модуля `vector_abs` (для этого выделяем ненужные сигналы, и удаляем их с помощью клавиши `Delete`).
By this point, the waveform likely has many signals. Remove the unnecessary ones, keeping only the internal signals of module `vector_abs` (select the unwanted signals and delete them with the `Delete` key).
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_26.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_26.png)
_Рисунок 26. Поведение внутренних сигналов модуля `vector_abs` на временной диаграмме._
_Figure 26. Behavior of internal signals of module `vector_abs` on the waveform._
В глаза сразу же бросается, что сигнал `max` внешне отличается от всех остальных — он ведет себя как 1-битный сигнал. Если все остальные сигналы 32-разрядные, то и сигнал `max` должен быть таким же. Перейдем к объявлению этого сигнала, чтобы это исправить (нажав правой кнопкой мыши, и выбрав `Go To Source Code`):
It is immediately apparent that signal `max` looks different from all the others — it behaves like a 1-bit signal. If all other signals are 32-bit, `max` should be as well. Let us navigate to the declaration of this signal to fix it (right-click and select `Go To Source Code`):
```Verilog
module vector_abs(
@@ -411,30 +413,30 @@ module vector_abs(
//...
```
Это странно, курсор был установлен на строку `.max(max)`, хотя раньше в этом случае курсор устанавливался на строку, где объявлялся выбранный сигнал. Но вот в чем дело, если мы просмотрим файл внимательно, то не обнаружим объявления сигнала вовсе. Как так вышло, что мы использовали необъявленный сигнал, а САПР не выдал нам ошибку? Дело в том, что стандарт [IEEE 1364-2005](https://ieeexplore.ieee.org/document/1620780) для языка **SystemVerilog** допускает подобное использование необъявленного сигнала. В этом случае, синтезатор неявно создаст одноименный одноразрядный сигнал, что и произошло.
This is strange — the cursor was placed on the line `.max(max)`, whereas previously it was placed on the line where the selected signal was declared. The reason is that if we look through the file carefully, we find no declaration of this signal at all. How did we use an undeclared signal without the EDA tool reporting an error? The [IEEE 1364-2005](https://ieeexplore.ieee.org/document/1620780) standard for **SystemVerilog** permits this usage. In such a case, the synthesizer implicitly creates a 1-bit signal with the same name — which is exactly what happened.
Для исправления этой ошибки, объявим сигнал `max` с корректной разрядностью и повторим моделирование.
To fix this error, declare the signal `max` with the correct bit-width and re-run the simulation.
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_27.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_27.png)
_Рисунок 27. Результат моделирования после объявления пропущенного сигнала._
_Figure 27. Simulation result after declaring the missing signal._
## Самостоятельная работа
## Independent Exercise
Число ошибок сократилось до 40! Мы явно на верном пути. Повторяем предыдущие шаги, вернувшись к первой ошибке:
The error count dropped to 40! We are clearly on the right track. Repeat the previous steps, returning to the first error:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_28.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_28.png)
_Рисунок 28. Первая ошибка в повторном моделировании._
_Figure 28. First error in the re-run simulation._
В этот раз первая ошибка осталась прежней, только теперь схема считает, что результат должен равняться шести (в прошлый раз схема выдавала `2`). Мы уже убедились, что в этом случае модель дает правильный результат, поэтому сразу перейдем к формирующим результат сигналам:
This time the first error is the same, except now the circuit computes the result as six (previously it returned `2`). We have already confirmed that the model gives the correct result here, so let us go straight to the signals that form the output:
![../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_29.png](../.pic/Vivado%20Basics/05.%20Bug%20hunting/fig_29.png)
_Рисунок 29. Поведение внутренних сигналов модуля `vector_abs` на временной диаграмме._
_Figure 29. Behavior of internal signals of module `vector_abs` on the waveform._
Видим, что значение сигнала `min_half`, формирующего значение выхода `abs` неверно (минимумом из `3` и `4` является `3`, `3/2 = 1`).
We can see that the value of signal `min_half`, which contributes to output `abs`, is incorrect (the minimum of `3` and `4` is `3`, and `3/2 = 1`).
Не отходя далеко от кассы, мы замечаем, что значение `min`, формирующее сигнал `min_half` неверно: его значение `4`, а должно быть `3`.
Looking closely, we also notice that the value of `min`, which drives `min_half`, is incorrect: it is `4`, but should be `3`.
Используя файлы исходного кода [проекта](./vector_abs/), попробуйте разобраться в последней обнаруженной нами ошибке.
Using the source files of the [project](./vector_abs/), try to identify the last bug we found.

30
Vivado Basics/06. RTL Analysis.md
View File

@@ -1,37 +1,37 @@
# Анализ RTL
# RTL Analysis
**RTL** (**register transfer level** — **уровень межрегистровых передач**) — это один из уровней абстракции при проектировании цифровой схемы, когда та описывается в виде регистров и логики передачи данных между этими регистрами.
**RTL** (**register transfer level**) is one of the abstraction levels in digital circuit design, where a circuit is described in terms of registers and the logic for data transfer between them.
Vivado предоставляет средства по анализу RTL-кода, позволяя обнаруживать и исправлять ошибки на раннем этапе, до выполнения моделирования и попытки синтезировать проект. Для того чтобы провести анализ, необходимо выполнить предобработку проекта (`Open Elaborated Design`, см. _рис. 1_).
Vivado provides RTL analysis tools, allowing you to detect and fix errors at an early stage, before running simulation or attempting to synthesize the project. To perform the analysis, you need to elaborate the project (`Open Elaborated Design`, see _fig. 1_).
![../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_1.png](../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_1.png)
_Рисунок 1. Инструменты анализа RTL в окне `Flow Navigator`._
_Figure 1. RTL analysis tools in the `Flow Navigator` window._
Итогом предобработки станет отображение графической схемы (подробнее рассказано в документе "[Этапы реализации проекта в ПЛИС](../Introduction/Implementation%20steps.md)"). Если схема не отобразилось, можно нажать на кнопку `Schematic`.
The result of elaboration is the display of a graphical schematic (described in more detail in the document "[Implementation Steps in FPGA](../Introduction/Implementation%20steps.md)"). If the schematic does not appear, click the `Schematic` button.
![../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_2.png](../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_2.png)
_Рисунок 2. Пример построения схемы для схемы, описанной в документе "[Менеджер проекта](./03.%20Project%20manager.md)"._
_Figure 2. Example of a schematic generated for the circuit described in the document "[Project Manager](./03.%20Project%20manager.md)"._
Допустим вы нашли ошибку, изменили код модуля и хотите увидеть обновленную схему. Вы нажимаете на кнопку `Schematic` у вас появляется новая вкладка, но схема на ней осталась без изменений. Дело в том, что открытие новой схемы требует повторной предобработки проекта. Для этого необходимо либо закрыть окно `Elaborated Design`, и открыть его заново, либо нажать на кнопку `Reload Design` вверху окна Vivado, которая появляется в информационном сообщении при обновлении кода модуля (см. _рис. 3_).
Suppose you found an error, modified the module code, and want to see the updated schematic. You click the `Schematic` button, a new tab opens, but the schematic has not changed. This is because opening a new schematic requires re-elaborating the project. To do this, either close the `Elaborated Design` window and reopen it, or click the `Reload Design` button at the top of the Vivado window, which appears in the informational message when the module code is updated (see _fig. 3_).
![../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_3.png](../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_3.png)
_Рисунок 3. Информационное сообщение о том, что предобработанный проект устарел в виду изменения исходников. Кнопка Reload позволяет выполнить повторную предобработку для обновленного кода._
_Figure 3. Informational message indicating that the elaborated design is outdated due to source changes. The Reload button triggers re-elaboration for the updated code._
Помимо построения схемы, Vivado выполнит её анализ, а обнаруженные проблемы будут отображены во вкладке `Messages`, которая расположена внизу окна Vivado (_рис. 4_).
In addition to building the schematic, Vivado will analyze it, and any detected issues will be shown in the `Messages` tab at the bottom of the Vivado window (_fig. 4_).
![../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_4.png](../.pic/Vivado%20Basics/06.%20RTL%20Analysis/fig_4.png)
_Рисунок 4. Окно с сообщениями о результатах выполненных операциях. Для удобства отображения, информационные сообщения скрыты, оставлены только предупреждения._
_Figure 4. Messages window showing the results of completed operations. For display convenience, informational messages are hidden; only warnings are shown._
Проблема окна сообщений заключается в том, что их число быстро накапливается и превращается в огромный поток, с которым тяжело работать даже с включенными фильтрами. Более того, сообщения сохраняются между запусками анализа, т.е. даже если вы исправите какую-то проблему — сообщение о ней так и останется до тех пор, пока вы не очистите окно сообщений.
The problem with the messages window is that the number of messages accumulates quickly and becomes an overwhelming stream that is difficult to work with even with filters enabled. Moreover, messages persist between analysis runs — even if you fix an issue, the message about it will remain until you manually clear the messages window.
Начиная с версии 2023.1 в Vivado появился специальный инструмент — линтер, который анализирует код и сообщает о проблемах в отдельном окне. Проблемы группируются по типам и список проблем очищается и генерируется повторно каждый раз, когда запускается линтер.
Starting from version 2023.1, Vivado includes a dedicated tool — a linter — that analyzes the code and reports issues in a separate window. Issues are grouped by type, and the list is cleared and regenerated every time the linter is run.
Если вы уже прочли документ "[Руководство по поиску функциональных ошибок](./05.%20Bug%20hunting.md)", вы можете заметить, что предупреждения, которые Vivado вывел в окно сообщений напрямую связаны с ошибками, которые мы обнаружили в процессе симуляции. Разница заключается в том, что Vivado вывел сообщения об этих ошибках практически мгновенно, в то время как нам для этого потребовалось проводить целое расследование. Именно в этом и заключается мощь данного инструмента — он позволяет найти большинство простых ошибок, давая возможность сосредоточиться на более сложных.
If you have already read the document "[Functional Bug Hunting Guide](./05.%20Bug%20hunting.md)", you may notice that the warnings Vivado displayed in the messages window are directly related to the errors we found during simulation. The difference is that Vivado reported these errors almost instantly, whereas we had to conduct a full investigation to find them. This is the power of this tool — it allows you to find most simple errors, freeing you to focus on more complex ones.
## Дополнительные материалы
## Additional Resources
Подробнее о взаимодействии с окном схемы можно прочитать в руководстве пользователя Vivado: ["Vivado Design Suite User Guide: Using the Vivado IDE (UG893)"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide) (раздел ["Using the Schematic Window"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide/Using-the-Schematic-Window)).
For more information on working with the schematic window, refer to the Vivado user guide: ["Vivado Design Suite User Guide: Using the Vivado IDE (UG893)"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide) (section ["Using the Schematic Window"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide/Using-the-Schematic-Window)).

34
Vivado Basics/07. Program and debug.md
View File

@@ -1,31 +1,31 @@
# Как прошить ПЛИС
# How to Program the FPGA
После того как вы описали и верифицировали модуль, остается запрототипировать его в ПЛИС. Для этого в большинстве папок лабораторных работ есть подпапка `board_files` в которой хранятся необходимые файлы. Обычно там будет находиться модуль верхнего уровня и файл ограничений, которые позволяют связать вашу логику с периферией, расположенной на плате `Nexys-A7`.
Once you have described and verified your module, the next step is to prototype it on an FPGA. For this purpose, most lab folders contain a `board_files` subfolder with the necessary files. Typically, it will contain a top-level module and a constraints file that connect your logic to the peripherals on the `Nexys-A7` board.
Для сборки итогового проекта вам необходимо:
To build the final project, you need to:
1. Добавить модуль верхнего уровня (содержащийся в файле с расширением `.sv`) в `Design Sources` вашего проекта.
2. Выбрать добавленный модуль в качестве модуля верхнего уровня вашего проекта.
1. Для этого нажмите по нему правой кнопкой мыши.
2. В контекстном меню выберете `Set as Top`.
3. Добавить файл ограничений (с расширением `.xdc`) в `Constraints` вашего проекта. Если такой файл уже есть в вашем проекте (а он будет в нём уже после первой лабораторной), вам необходимо заменить содержимое старого файла содержимым нового. Ограничения меняются от лабораторной к лабораторной.
1. Add the top-level module (contained in a file with the `.sv` extension) to the `Design Sources` of your project.
2. Set the added module as the top-level module of your project.
1. Right-click on it.
2. Select `Set as Top` from the context menu.
3. Add the constraints file (with the `.xdc` extension) to the `Constraints` of your project. If such a file already exists in your project (and it will, starting from the first lab), you need to replace the contents of the old file with the contents of the new one. Constraints change from lab to lab.
После выполнения указанных шагов, ваш проект готов к генерации битстрима — двоичного файла, с помощью которого реконфигурируется ПЛИС.
After completing these steps, your project is ready for bitstream generation — the binary file used to reconfigure the FPGA.
По сути, весь процесс генерации битстрима и конфигурациии оным ПЛИС сводится к последовательному нажатию следующих четырех кнопок в группе `PROGRAM AND DEUBG` окна `Flow Navigator`, которые представлены на _рис. 1_.
In essence, the entire process of generating the bitstream and programming the FPGA comes down to sequentially clicking the following four buttons in the `PROGRAM AND DEBUG` group of the `Flow Navigator` window, shown in _fig. 1_.
![../.pic/Vivado%20Basics/07.%20Program%20and%20debug/fig_1.png](../.pic/Vivado%20Basics/07.%20Program%20and%20debug/fig_1.png)
_Рисунок 1. Порядок выполнения действий для компиляции проекта и прошивки ПЛИС._
_Figure 1. Steps for compiling the project and programming the FPGA._
Нажатие на кнопку Generate Bitstream позволяет сгенерировать двоичный код для конфигурации ПЛИС. В случае, если перед этим не были выполнены этапы синтеза и имплементации, появятся всплывающие окна, предлагающие выполнить эти этапы. Вам достаточно утвердительно отвечать во всех всплывающих окнах (варианты `YES`/`OK`, в зависимости от состояния вашего проекта, число появляющихся окон будет различным). Последним окном, информирующим о том, что двоичный файл готов будет `Bitstream Generation Completed` (в случае, если все этапы были выполнены без ошибок).
Clicking `Generate Bitstream` generates the binary configuration file for the FPGA. If the synthesis and implementation steps have not been completed beforehand, pop-up windows will appear prompting you to run them. Simply confirm all pop-up windows (using `YES`/`OK` — the number of windows will vary depending on the state of your project). The final window, confirming that the binary file is ready, will be `Bitstream Generation Completed` (provided all steps completed without errors).
Остаётся прошить ПЛИС. Для этого подключите отладочный стенд к USB-порту компьютера и включите на стенде питание.
Now you need to program the FPGA. Connect the development board to the USB port of your computer and power it on.
Затем запустите менеджер аппаратуры Vivado. Для этого нажмите на кнопку `Open Hardware Manager` (кнопка 2 на _рис. 1_).
Then launch the Vivado Hardware Manager by clicking `Open Hardware Manager` (button 2 in _fig. 1_).
После, необходимо подключиться к ПЛИС. Для этого необходимо нажать на кнопку `Open Target` (кнопка 3 на _рис. 1_) и в контекстном меню выбрать вариант `Auto Connect`.
Next, connect to the FPGA by clicking `Open Target` (button 3 in _fig. 1_) and selecting `Auto Connect` from the context menu.
И последним шагом остается прошить ПЛИС нажатием на кнопку `Program Device` (кнопка 4 на _рис. 1_). Появится всплывающее окно, предлагающее выбрать двоичный файл конфигурации, поле которого будет автоматически заполнено путем к последнему сгенерированному файлу. Вам не нужно ничего менять, только нажать на кнопку `Program`.
The final step is to program the FPGA by clicking `Program Device` (button 4 in _fig. 1_). A pop-up window will appear asking you to select the binary configuration file; the field will be automatically filled with the path to the last generated file. You do not need to change anything — simply click `Program`.
После этого появится окно с индикатором реконфигурации ПЛИС. Когда окно закроется, ПЛИС будет сконфигурирована под прототип вашего модуля.
A window with an FPGA reconfiguration progress indicator will then appear. Once the window closes, the FPGA will be configured as the prototype of your module.

22
Vivado Basics/08. Code processing errors.md
View File

@@ -1,27 +1,27 @@
# Руководство по работе с ошибками обработки кода
# Guide to Handling Code Processing Errors
Некоторые ошибки (например ошибки синтаксиса или иерархии) могут привести к тому, что САПР не сможет построить схему или запустить симуляцию.
Some errors (such as syntax errors or hierarchy errors) may prevent the EDA tool from building the schematic or launching simulation.
Без должного опыта, при подобных ошибках можно растеряться, т.к. всплывающие окна, сообщающие об этих ошибках малоинформативны (см. _рис. 1-2_).
Without sufficient experience, these errors can be confusing, as the pop-up windows reporting them are not very informative (see _fig. 1–2_).
Предположим, мы забыли поставить точку с запятой в конце одного из присваиваний, и попробовали запустить моделирование.
Suppose we forgot to place a semicolon at the end of one of the assignments, and then tried to launch simulation.
В результате, всплывающие окна, представленные на _рис. 1-2_.
As a result, the pop-up windows shown in _fig. 1–2_ will appear.
![../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_01.png](../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_01.png)
_Рисунок 1. Первое всплывающее окно при попытке запустить моделирование проекта с синтаксической ошибкой._
_Figure 1. First pop-up window when attempting to launch simulation with a syntax error in the project._
![../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_02.png](../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_02.png)
_Рисунок 2. Второе всплывающее окно при попытке запустить моделирование проекта с синтаксической ошибкой._
_Figure 2. Second pop-up window when attempting to launch simulation with a syntax error in the project._
Во втором окне есть кнопка `Open Messages View`. Нажмём её. Будет активировано окно сообщений, представленное на _рис. 3_.
The second window contains an `Open Messages View` button. Click it. The messages window shown in _fig. 3_ will be activated.
![../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_03.png](../.pic/Vivado%20Basics/08.%20Code%20processing%20errors/fig_03.png)
_Рисунок 3. Окно сообщений после неудачной попытки запуска симуляции._
_Figure 3. Messages window after a failed attempt to launch simulation._
Сообщения из раздела `Vivado commands` на _рис. 2_ дают мало информации. Однако здесь же есть критические предупреждения о синтаксической ошибке с возможностью перейти к строчке в файле, вызвавшей это предупреждение. Разумеется, не всегда САПР может сообщить доступным языком в чем именно ошибка, в данном случае, он просто обнаружил что ключевое слово `end` встретилось не там, где оно должно было бы быть (оно встретилось до завершения оператора присваивания, который должен был быть завершен символом `;`). В этом случае, вам необходимо самим разобраться в чем именно заключается ошибка (для этого вы можете кликнуть по гиперссылке в критическом предупреждении — откроется редактор с местом ошибки).
The messages in the `Vivado commands` section in _fig. 2_ provide little information. However, there are also critical warnings about the syntax error, with a link to the line in the file that triggered the warning. Of course, the EDA tool cannot always clearly explain what the error is — in this case, it simply detected that the keyword `end` appeared in an unexpected location (it was encountered before the assignment operator was terminated with a `;`). In this situation, you need to figure out the exact nature of the error yourself (you can click the hyperlink in the critical warning to open the editor at the location of the error).
Помните, что большая часть сообщений в данном окне сохраняется даже если ошибка будет исправлена, поэтому рекомендуется очищать окно сообщений, в случае если появились ошибки и уже сложно понять какие из них старые, а какие из них новые. Сделать это можно, нажав на иконку корзины в окне сообщений. При этом удалятся не все ошибки, а только те, которые были вызваны процессами, запущенными пользователем. К примеру, если очистить окно сообщений, не исправив указанную ошибку, пропадут только ошибки из раздела `Vivado commands`. Дело в том, что критические предупреждения появились не после того, как мы попытались запустить моделирования, а после того, как Vivado автоматически запустил инструменты анализа кода. Делает он это автоматически каждый раз, когда сохраняется файл. Эти ошибки пропадут только когда повторный анализ покажет, что они были исправлены.
Keep in mind that most messages in this window persist even after the error is fixed, so it is recommended to clear the messages window when errors appear and it becomes difficult to distinguish old messages from new ones. This can be done by clicking the trash can icon in the messages window. Note that not all errors will be cleared — only those triggered by processes launched by the user. For example, if you clear the messages window without fixing the error, only the messages from the `Vivado commands` section will disappear. This is because the critical warnings appeared not when we attempted to launch simulation, but when Vivado automatically ran its code analysis tools. Vivado does this automatically every time a file is saved. These warnings will only disappear once a subsequent analysis confirms they have been resolved.

26
Vivado Basics/README.md
View File

@@ -1,18 +1,18 @@
# Основа работы с Vivado
# Vivado Basics
Цикл лабораторных работ создан, чтобы вы могли на практике отработать полученные знания по архитектурам процессорных систем, увидеть "изнутри", как "бегают нолики и единицы", подобно тому, как они бегают и в ваших компьютерах.
The lab series is designed for you to apply the knowledge gained on processor system architectures in practice — to see "from the inside" how zeros and ones flow through a circuit, just as they do in your own computers.
Для эффективного погружения в лабораторные работы используется САПР **Vivado**. Это довольно сложный инструмент, на одно только осваивание которого требуется порядочное количество времени.
The EDA tool **Vivado** is used for effective engagement with the lab work. It is a fairly complex tool that requires a considerable amount of time to learn on its own.
Дабы сократить порог вхождения в освоение этого инструмента, был написан ряд материалов по описанию базовых сценариев использования, который представлен в данной папке.
To lower the barrier to entry, a set of materials covering the basic usage scenarios has been written and is presented in this folder.
Здесь находятся следующие документы:
The following documents are available here:
1. [Создание нового проекта под отладочный стенд Nexys A7](./01.%20New%20project.md);
2. [Навигатор по маршруту проектирования](./02.%20Flow%20Navigator.md);
3. [Менеджер проекта](./03.%20Project%20manager.md);
4. [Как запустить симуляцию в Vivado](./04.%20Simulation.md);
5. [Руководство по поиску функциональных ошибок](./05.%20Bug%20hunting.md);
6. [Анализ RTL](./06.%20RTL%20Analysis.md);
7. [Как прошить ПЛИС](./07.%20Program%20and%20debug.md);
8. [Руководство по работе с ошибками обработки кода](08.%20Code%20processing%20errors.md)
1. [Creating a New Project for the Nexys A7 Development Board](./01.%20New%20project.md);
2. [Flow Navigator](./02.%20Flow%20Navigator.md);
3. [Project Manager](./03.%20Project%20manager.md);
4. [How to Run Simulation in Vivado](./04.%20Simulation.md);
5. [Functional Bug Hunting Guide](./05.%20Bug%20hunting.md);
6. [RTL Analysis](./06.%20RTL%20Analysis.md);
7. [How to Program the FPGA](./07.%20Program%20and%20debug.md);
8. [Guide to Handling Code Processing Errors](08.%20Code%20processing%20errors.md)

8
Vivado Basics/vector_abs/README.md
View File

@@ -1,7 +1,7 @@
# Модуль приближенного вычисления длины вектора
# Approximate Vector Length Computation Module
Модуль `vector_abs` предназначен для вычисления приближенной длины вектора в евклидовом пространстве (выражения `sqrt(a^2+b^2)`). Для эффективного использования логических вентилей используется следующее приближение:
The `vector_abs` module is designed to compute the approximate length of a vector in Euclidean space (i.e., the expression `sqrt(a^2+b^2)`). To make efficient use of logic gates, the following approximation is applied:
`sqrt(a^2+b^2) ≈ max + min/2`, где max и min — наибольшее и наименьшее из пары чисел соответственно [**Ричард Лайонс: Цифровая обработка сигналов, Глава 13.2, стр. 475**].
`sqrt(a^2+b^2) ≈ max + min/2`, where max and min are the larger and smaller of the two numbers, respectively [**Richard Lyons: Understanding Digital Signal Processing, Chapter 13.2, p. 475**].
Для определения максимума/минимума используется модуль `max_min`, для вычисления деления пополам используется модуль `half_divider`.
The `max_min` module is used to determine the maximum/minimum values, and the `half_divider` module is used to compute the division by two.