Commit 26b26732 authored by Mamta Shukla's avatar Mamta Shukla

doc: Remove sources for rtd

Signed-off-by: Mamta Shukla's avatarMamta Shukla <mamta.ramendra.shukla@cern.ch>
parent e477506b
Pipeline #2328 canceled with stage
No preview for this file type
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.. _build:
Build
==================
Using Vitis
-----------------
Refer `this <https://ohwr.org/project/spec7/wikis/uploads/ca8f150af87f5119faa94b84539f0ea0/SPEC7.pdf>`_
Using Command line
------------------------
1. Create ``.bif`` file eg: ``output.bif``
.. code-block::
$ vi output.bif
Contents of .bif file:
.. code-block::
/* Linux */
the_ROM_image:
{
[bootloader] <xsct_ws/zynq_fsbl/Release/-path>zynq_fsbl.elf
<xsct_ws/spec7_custom/hw/-path to bitstream>/spec7_custom.bit
<path-to-u-boot>/u-boot.elf
}
`output.bif` with offset support for two designs
.. code-block::
/*Linux*/
the_ROM_image:
{
[bootloader] zynq_fsbl.elf
tandem_gateware.bit
u-boot.elf
[offset = 0x20000000]reference_gateware.bit
}
2. Build using bootgen command:
Setup environment
.. code-block::
$ source /tools/Xilinx/Vitis/2019.2/settings64.sh
Run bootgen
.. code-block::
bootgen -image output.bif -arch zynq -w -o BOOT.bin
Use this image to load in QSPI from command line
.. code-block::
program_flash -f BOOT.bin -fsbl </path/to/fsbl>/zynq_fsbl.elf -flash_type qspi-x8-dual_parallel -blank_check -url tcp:localhost:3121
Using Script
--------------------
BOOT.bin can be generated by automating above steps.
Refer `../sw/boot` ``Build.sh`` script in `spec7 ohwr repo <https://ohwr.org/project/spec7>`_ , run:
.. code-block::
$ ./Boot_Build.sh -t -r -o -u -h
.. code-block::
Usage: $0 -t {Tandem_bitfile} -r {Reference_bitfile} -o {Memory_Offset};
-t {Tandem_bitfile} location of the bitfile used in tandem PCIe boot. Default is the most recent bitfile in spec7/hdl/syn/ containing the word "tandem".;
-r {Reference_bitfile} location of the bitfile used in the reference design. Default is the most recent bitfile in spec7/hdl/syn/ containing the word "ref".;
-o {Memory_Offset} the DDR3 Memory offset where the reference design is loaded into. Default is 0x1000000.;
-u {uboot uart channel} The uart channel number where Cout and Cin is directed. Default is 0.;
-h Prints this help message.;
It will generate all require components i.e FSBL, U-boot, Boot.bin in `/output` directory
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'SPEC7'
author = 'David Cobas,Pascal Bos,Mamta Shukla, Peter Jansweijer, Javier D. Garcia-Lasheras'
# The full version, including alpha/beta/rc tags
release = '1.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
#extensions = [
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'sphinx.ext.graphviz',
'sphinx.ext.coverage',
'myst_parser'
# 'rinoh.frontend.sphinx'
]
autodoc_member_order = 'bysource'
# Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
master_doc = 'index'
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
todo_include_todos = True
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
html_show_sphinx = False
htmlhelp_basename ='SPEC7'
# -- Options for LaTeX output ---------------------------------------------
latex_engine = 'pdflatex'
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
#
'pointsize': '11pt',
#'fontpkg': r'''
#\setmainfont{Bitstream Charter}
#\setsansfont{Lato}
#\setmonofont[Scale=0.92]{FreeMono}
#''',
# Additional stuff for the LaTeX preamble.
#
'preamble' : '' ,
# Latex figure (float) alignment
#
'figure_align': 'htbp',
#'sphinxsetup': 'VerbatimColor={rgb}{.97,.98,.97}',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'SPEC7.tex', u'SPEC7 Documentation', u'','manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#
# latex_use_parts = False
# If true, show page references after internal links.
#
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
#
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
#
# latex_appendices = []
# It false, will not define \strong, \code, itleref, \crossref ... but only
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
# packages.
#
# latex_keep_old_macro_names = True
# If false, no module index is generated.
#
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
#man_pages = [
# (master_doc, 'SPEC7', u'SPEC7 Documentation',
# [author], 1)
#]
# If true, show URL addresses after external links.
#
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'SPEC7', u'SPEC7 Documentation',
author, 'SPEC7', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
autodoc_default_options = {
'member-order': 'bysource',
}
.. _fsbl:
FSBL
=========
FSBL (First stage bootloader) built using Vitis v2019.2 after successfully
generating the bitstream for above design and exporting as hardware xsa
file in the platform. This provides a golden design along with FSBL,
which can be booted via writing to QSPI Flash Memory
Build
------
Using Vitis GUI
++++++++++++++++++
Steps to build:
1. Export the design as xsa file for later developments in Vitis
2. Add platform project name and location
3. Modify BSP Settings and enable xilffs
4. Add application project and select ZYNQ_FSBL
5. Go to Next
6. Check the sources initialised on left side
7. Run Build
More details refer `this <https://ohwr.org/project/spec7/wikis/uploads/ca8f150af87f5119faa94b84539f0ea0/SPEC7.pdf>`_
Command line
++++++++++++++++++
Require: Vitis 2019.2
1. SetUp Environment
.. code-block::
$ source /tools/Xilinx/Vitis/2019.2/settings64.sh
2. Enable Xilinx Software Command Line Tool
.. code-block::
$ xsct%
3. Setup workspace
.. code-block::
$ setws </path/to/a/directory>
4. Export xsa file and setup platform project
.. code-block::
$ platform create -name <platform/name eg:spec7_custom> -hw </<path to xsa>/spec7_custom.xsa> -no-boot-bsp
5. Check the active platform:
.. code-block::
$ platform active
6. Create domain
.. code-block::
$ domain create -name "fsbl_domain" -os standalone -proc ps7_cortexa9_0
7. Check the active domain with:
.. code-block::
$ domain active
8. Add library before building FSBL:
.. code-block::
$ bsp setlib xilffs
9. Check stdin and stdout configuration in the BSP:
.. code-block::
$ bsp config stdin ps7_uart_1
$ bsp config stdout ps7_uart_1
10. Build the platform:
.. code-block::
$ platform generate
11. Add system project
First, we create the application for the FSBL targeting the already existing platform and the specific domain and specifying the template Zynq FSBL. In addition, we will select the spec7_custom_system as the name of the system that will be created to host the application:
.. code-block::
$ app create -name zynq_fsbl -template {Zynq FSBL} -platform spec7_custom -domain fsbl_domain -sysproj spec7_custom_system
12. Config and Build FSBL:
.. code-block::
$ app config -name zynq_fsbl build-config release
$ app config -name zynq_fsbl build-config
$ app build -name zynq_fsbl
This will generate ``zynq_fsbl.elf`` file in workspace directory set using step 2 as ``<path/to/directory_ws/zynq_fsbl/Release/zynq_fsbl.elf>``.
Tcl script
+++++++++++++++++++++
All the above steps can be automated using Tcl script and built with make.
Source: In `spec7 ohwr repo <https://ohwr.org/project/spec7/tree/spec7_golden/sw/fsbl>`_ ``sw/fsbl/``, run
.. code-block::
$ make
This will generate zynq_fsbl.elf in ``/output`` directory.
.. _hdl:
Firmware
============
SPEC7 Golden Architecture
This design was build to provide PCIe enumeration within 100ms
.. image:: media/spec7_golden.png
SPEC7 Reference design with XDMA for Remote Upgrade
This design was built on SPEC7 Reference Design with addititonal BAR 4 for PCIe to upload new firmware to PS-DDR via
AXI DMA and PCIe core with addon Virtual UART provided through AXI Uartlite Core to direct PS to load firmware in
PL
.. image:: media/spec7_ref_dma.png
---------------------------------------------------------
To add two Tandem and Reference design in one BOOT.bin
-------------------------------------------------------
1. Script Build.sh in ``sw/scripts/boot`` intiates build for FSBL and Uboot
It also creates ``spec7.bif`` file which consists of path for all output obtained i.e bitstream, elf files located in ``output`` directory
.. code-block::
./Build.sh --t <specify Tandem Design> --r <reference design> --o <offset>
2. The above step will create BOOT.bin in output directory which can be flashed directly to flash memory
.. code-block::
program_flash -f BOOT.bin -fsbl </path/to/fsbl>/zynq_fsbl.elf -flash_type qspi-x8-dual_parallel -blank_check -url tcp:localhost:3121
3. To automate loading of second design, it's possible in two ways
Create environment variable in U-boot in Runtime
++++++++++++++++++++++++++++++++++++++++++++++++++++
.. code-block::
SPEC7> sf probe 0 0 0
SPEC7> sf erase 0x2000000 0x1000000
SPEC7> sf write ${loadbit_addr} 0x2000000 ${filesize}
SPEC7> fpga loadb 0 ${loadbit_addr} ${filesize}
The above commands are for test, where 0x2000000 specifies the offset defined in BOOT.bin
Automatic gateware update from QSPI
++++++++++++++++++++++++++++++++++++
In order to allow for automatic loading of the gateware from QSPI using the UBoot, first we define the following environment variables:
.. code-block::
SPEC7> setenv bootdelay "0"
SPEC7> setenv gateware_size 0x1000000
SPEC7> setenv qspi_gateware_offset 0x2000000
The meaning for each of these variables are:
- ``bootdelay``: this contains the maximum value of the countdown that UBoot perform before executing the `bootcmd`. By setting it to zero, we save a precious time at startup.
- ``gateware_size``: we define this auxiliary variable that specify the size of the slot containing the gateware that we want to move from QSPI to DDR. We set the value to 16 MiB, i.e. the full size of the slot.
- ``qspi_gateware_offset``: we define this auxiliary variable containing the QSPI offset of the slot containing the gateware we want to load. In this case, we are pointing to the Slot 2, but we can easily modify the slot to be used by editing this variable.
Now, we create the boot command to read the gateware from the desired QSPI slot to DDR, then from DDR to FPGA, and finally go back to the U-boot prompt:
.. code-block::
SPEC7> editenv bootcmd_gateware
edit: sf probe 0 0 0 && sf read ${loadbit_addr} ${qspi_gateware_offset} ${gateware_size} && fpga loadb 0 ${loadbit_addr} 0x1
**Note**: because we are using bitstream in `bit` format, the `fpga loadb` command doesn't require the exact size of the bitstream, just a non zero value, as the size is already encoded in the bitstream header.
In order to boot execute this command at start-up, we must assign the `bootcmd` variable and save the environment:
.. code-block::
SPEC7> setenv bootcmd "run bootcmd_gateware"
SPEC7> saveenv
Adding the above environment during building U-boot using ``make menuconfig`` or adding in ``config``
.. code-block::
#define CONFIG_EXTRA_ENV_SETTINGS \
"bootdelay = 0"\
"gateware_size =0x1000000" \
"qspi_gateware_offse= 0x2000000" \
" bootcmd_gateware = sf probe 0 0 0 && sf read ${loadbit_addr} ${qspi_gateware_offset} ${gateware_size} && fpga loadb 0 ${loadbit_addr} 0x1" \
"bootcmd = run bootcmd_gateware"
.. SPEC7 documentation master file, created by
sphinx-quickstart on Mon Jun 28 00:25:37 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
SPEC7 documentation
=================================
.. toctree::
:maxdepth: 2
:caption: Table of Contents:
introduction
hdl
fsbl
uboot
build
kernel
.. _introduction:
Introduction
=============
.. figure:: media/Block.png
References:
++++++++++++++
#. `Wiki <https://ohwr.org/project/spec7/wikis/home>` -https://ohwr.org/project/spec7/wikis/home
#. `OHWR Repo <https://ohwr.org/project/spec7>` -https://ohwr.org/project/spec7
#. `Initial Document <https://ohwr.org/project/spec7/wikis/uploads/ca8f150af87f5119faa94b84539f0ea0/SPEC7.pdf>`
.. _kernel:
Kernel
==================
From Sources
++++++++++++++++++++
1. Get the sources
.. code-block::
git clone https://github.com/Xilinx/linux-xlnx.git
cd linux-xlnx
git checkout xilinx-v2019.2.01
2. Set environment for Cross-Compilation:  
.. code-block::
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm
3. Configuration
.. code-block::
$make xilinx_zynq_defconfig
4. Build
.. code-block::
$ make -j<cores>
$ mkimage -A arm -O linux -T kernel -C none -a 0x80008000 -e 0x80008000 -n "Linux kernel" -d linux-xlnx/arch/arm/boot/zImage uImage
From script
+++++++++++++++++++++++
Above steps are automated using Makefile and can be found in `spec7 ohwr repo <>`
.. code-block::
output=../../output
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm
defconfig=xilinx_zynq_defconfig
kernel := linux-xlnx
defconfig:
@$(MAKE) -C $(kernel) $(defconfig)
@$(MAKE) -C $(kernel)
mkimage -A arm -O linux -T kernel -C none -a 0x80008000 -e 0x80008000 -n "Linux kernel" -d linux-xlnx/arch/arm/boot/zImage uImage
cp uImage $(output)
menuconfig:
@$(MAKE) -C $(kernel) menuconfig
clean:
@$(MAKE) -C $(kernel) clean
This will generate Kernel ``uImage`` in output directory, which can be stored in flash or loaded over TFTP
Petalinux Flow
++++++++++++++++++++++++++
1. Download Petalinux sources from Xilinx official website
2. In Petalinux directory
.. code-block::
$ source settings.ch
3. To create the Project
.. code-block::
$ petalinux-create --type project --template zynq --name spec7_kernel
4. Copy .xsa generated from Vivado in Project directory and then build
.. code-block::
$ petalinux-config --get-hw-description
5. To config u-boot, and Linux
.. code-block::
$ petalinux-config -c u-boot
$ petalinux-config -c kernel
6. Now to build everything
.. code-block::
$ petalinux-build
7. All the generated output will be availabe in ``images`` folder
8. To create final BOOT.BIN, run this inside
.. code-block::
$ petalinux-package --boot --fsbl zynq_fsbl.elf --fpga system.bit --u-boot --kernel
myst_parser
docutils
sphinx
sphinx_rtd_theme
recommonmark
decorator
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment