Skip to content

Commit 04dca02

Browse files
amd-vserbuamd-vserbu
authored
Documentation for bootstrapping AVED (#69)
* Bootstrap AVED documentation Signed-off-by: Vlad-Gabriel Serbu <Vlad-Gabriel.Serbu@amd.com>
1 parent f54ce39 commit 04dca02

4 files changed

Lines changed: 185 additions & 0 deletions

File tree

‎docs/howto/install-from-packages.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,13 @@ passing (PF0, PF1, PF2, VRTD).
247247
Program the Board
248248
==================
249249

250+
.. note::
251+
252+
This step assumes the AMI driver is already bound to PF0
253+
(``10ee:50b4``). If your V80 has never been programmed with AVED — for
254+
example, a brand-new board — first complete
255+
:doc:`/tutorials/admin/bootstrap-aved` to install AVED via JTAG.
256+
250257
After installing the packages, the board's flash memory must be programmed
251258
with the static shell before the system can be used. This step is required:
252259

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ management, and memory operations.
1919
tutorials/user/buffers-and-memory
2020
tutorials/user/emulation-and-simulation
2121
tutorials/admin/platform-setup
22+
tutorials/admin/bootstrap-aved
2223
tutorials/admin/device-management
2324
tutorials/admin/vrtd-configuration
2425

‎docs/tutorials/admin/bootstrap-aved.rst‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
..
2+
comment:: SPDX-License-Identifier: MIT
3+
comment:: Copyright (C) 2025 Advanced Micro Devices, Inc
4+
5+
#########################
6+
Bootstrapping with AVED
7+
#########################
8+
9+
This tutorial walks an administrator through the one-time JTAG step
10+
required to install **AVED** (the Alveo Versal Example Design) on an
11+
AMD Alveo V80 board. AVED provides the AMC firmware and the PCIe
12+
management function (PF0, device ID ``0x50B4``) that the SLASH stack
13+
binds to via the ``ami`` kernel driver.
14+
15+
When you need this tutorial
16+
===========================
17+
18+
The rest of the SLASH platform-setup flow — including
19+
``ami_tool cfgmem_program`` for writing the SLASH static shell —
20+
requires that ``ami`` is already bound to PF0. That, in turn, requires
21+
a valid AVED image in the V80's OSPI flash. Follow this tutorial when:
22+
23+
- the V80 is **brand new** and has never had AVED programmed, or
24+
- the V80's OSPI flash has been corrupted or wiped and PF0 no longer
25+
enumerates over PCIe, or ami repports errors (such as ``NO_AMC```)
26+
27+
Boards that already enumerate PF0 (visible as ``10ee:50b4`` in
28+
``lspci``) can skip this tutorial and go directly to
29+
:doc:`platform-setup`.
30+
31+
Prerequisites
32+
=============
33+
34+
**Hardware:**
35+
36+
- AMD Alveo V80 installed in a PCIe slot.
37+
- USB cable from the host to the V80's onboard USB-JTAG.
38+
39+
**Software:**
40+
41+
- AMD Vivado 2025.1.
42+
43+
Download the AVED Deployment Archive
44+
=====================================
45+
46+
AVED is published by AMD as a prebuilt deployment archive. Download
47+
the archive for the V80 from the AVED documentation portal:
48+
49+
- AVED documentation: https://xilinx.github.io/AVED/
50+
- V80 member-portal page: https://www.xilinx.com/member/v80.html
51+
52+
Extract the archive on the host. The relevant files for this tutorial
53+
are located under ``flash_setup/``:
54+
55+
.. list-table::
56+
:header-rows: 1
57+
:widths: 40 60
58+
59+
* - File
60+
- Purpose
61+
* - ``flash_setup/versal_change_boot_mode.tcl``
62+
- XSDB script that switches the Versal device to JTAG boot mode.
63+
* - ``flash_setup/v80_initialization.pdi``
64+
- Initialization PDI loaded over JTAG before flashing OSPI.
65+
* - ``flash_setup/fpt_setup_<vbnv>_<release>.pdi``
66+
- Flash Partition Table setup PDI written to OSPI.
67+
68+
Switch the V80 to JTAG Boot Mode
69+
================================
70+
71+
By default the V80 boots from OSPI. To program a fresh board over
72+
JTAG, the Versal device must first be switched to JTAG boot mode.
73+
Source the Vivado settings, then launch ``xsdb`` and source the
74+
``versal_change_boot_mode.tcl`` script shipped with the archive:
75+
76+
.. code-block:: bash
77+
78+
source <path-to-vivado>/settings64.sh
79+
xsdb
80+
81+
At the ``xsdb%`` prompt:
82+
83+
.. code-block:: tcl
84+
85+
connect
86+
targets -set -filter {name =~ "Versal*"}
87+
source flash_setup/versal_change_boot_mode.tcl
88+
89+
The script reconfigures the boot-mode register on the Versal device
90+
so that subsequent JTAG operations from Hardware Manager will be
91+
accepted.
92+
93+
See `AVED JTAG Boot Recovery
94+
<https://xilinx.github.io/AVED/amd_v80_gen5x8_exdes_1_20231204/AVED+JTAG+Boot+Recovery.html>`_
95+
for the upstream reference.
96+
97+
Program OSPI Flash via Vivado Hardware Manager
98+
==============================================
99+
100+
With the V80 in JTAG boot mode, launch Vivado Hardware Manager and
101+
program the OSPI flash:
102+
103+
1. Launch Vivado and open Hardware Manager
104+
(*Flow* → *Open Hardware Manager*).
105+
2. *Open Target* → *Auto Connect*. The V80 should appear as
106+
``xcv80_1``.
107+
3. Right-click ``xcv80_1`` → *Add Configuration Memory Device*.
108+
4. Select the ``cfgmem-2048-ospi-x8-single`` part.`
109+
5. Program the configuration memory using
110+
``flash_setup/fpt_setup_<vbnv>_<release>.pdi`` together with
111+
``flash_setup/v80_initialization.pdi``. For the address range
112+
select **Entire Configuration Memory Device**.
113+
6. Wait for Hardware Manager to report **Flash Programming
114+
Completed Successfully**.
115+
116+
For the upstream step-by-step reference, see `AVED Updating FPT Image
117+
in Flash <https://xilinx.github.io/AVED/amd_v80_gen5x8_24.1_20241002/AVED+Updating+FPT+Image+in+Flash.html>`_
118+
and `AVED Device Programming
119+
<https://xilinx.github.io/AVED/amd_v80_gen5x8_exdes_2_20240408/AVED+-+Device+Programming.html>`_.
120+
121+
Cold-Reboot the Host
122+
====================
123+
124+
A full power cycle is required after flashing — a soft ``reboot``
125+
will not re-read the Versal boot-mode pins. Shut the host down
126+
completely, then power it back on:
127+
128+
.. code-block:: bash
129+
130+
sudo shutdown -h now
131+
132+
After the host powers back on, the V80 boots from OSPI and AVED
133+
becomes active.
134+
135+
Verify
136+
======
137+
138+
Confirm that PF0 enumerates on the PCIe bus:
139+
140+
.. code-block:: bash
141+
142+
lspci -d 10ee:50b4
143+
144+
You should see one entry per V80 board. If the ``ami`` driver is
145+
already installed on this host, ``ami_tool`` will also report the
146+
card:
147+
148+
.. code-block:: bash
149+
150+
sudo ami_tool overview
151+
152+
The reported ``logic_uuid`` should match the UUID listed in the
153+
AVED archive's ``version.json``.
154+
155+
.. note::
156+
157+
If you are following the package build flow on a fresh board, you
158+
will not have the ``ami`` driver or ``ami_tool`` installed yet. That
159+
is expected at this stage — confirming that the board enumerates on
160+
PCIe via ``lspci`` is sufficient. Continue on to :doc:`platform-setup`
161+
to install the SLASH stack, which brings in ``ami`` and ``ami_tool``.
162+
163+
Next Steps
164+
==========
165+
166+
With AVED bootstrapped and PF0 visible, continue with the regular
167+
platform-setup flow:
168+
169+
- :doc:`platform-setup` — install the SLASH stack and program the
170+
SLASH static shell over PCIe with ``ami_tool cfgmem_program``.

‎docs/tutorials/admin/platform-setup.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,13 @@ The following table summarises what each package provides:
326326
Program the Board
327327
=================
328328

329+
.. note::
330+
331+
This step assumes the AMI driver is already bound to PF0
332+
(``10ee:50b4``). If your V80 has never been programmed with AVED — for
333+
example, a brand-new board — first complete :doc:`bootstrap-aved` to
334+
install AVED via JTAG.
335+
329336
After installing the packages, the board's flash memory must be programmed
330337
with the static shell before the system can be used. This step is required:
331338

0 commit comments

Comments
 (0)