
Welcome to STYNQ!

*******************************************************************
**  ABOUT STYNQ
*******************************************************************

This release is meant to be a competitor to Petalinux and PYNQ.

One advantage of STYNQ is that it is designed for simplicity, as much
as is possible.  Build steps are kept as indepentent as then can be,
and in their best forms so that they can be configured as they are
naturally configured.

Another advantage is that it is designed to work without Board Support
Packages, so that it is more easily portable to boards that don't have
them.  It includes a simpler process for obtaining working device
trees, and a simplified process for conveying hardware information
from Vivado into a C++ program.

Another advantage is that it allows complications of creating Linux
kernel modules to be avoided, instead supporting direct communication
to the hardware around the kernel.  This is much simpler, although it
does require that programs run as root.

Another advantage is that STYNQ is based on Debian Linux, so that once
a STYNQ system is installed new packages can easily be added with "apt".

Another advantage is that STYNQ uses a mainline Linux kernel, not
the Linux kernel with Xilinx-maintained modifications.  This avoids
some oddities and bugs.

*******************************************************************
**  BUILDING STYNQ for RFSoC4x2 boards
*******************************************************************

Building is from a Linux machine, typically running Ubuntu.

The RFSoC4x2 is the first target for STYNQ, so things are perhaps
a bit more polished, and ready to go with an example.

First, cd to STYNQ_BASE and run build.sh.  This first builds the
Linux kernel in the "kernel" directory.  Then it takes an XSA file
in STYNQ_BASE/boot/inputs/XSA/ and produces the boot files
BOOT.BIN, BOOT.SCR, and image.ub in boot/out/.

Note that this XSA file came from the design in
STYNQ_RFSoC4x2_Example_1/Vivado/.  The key things in the XSA file for
generating boot files are the settings of the ZYNQMP processor block
in the block design.  So long as the same settings are used in other
designs, the same boot files can be used in those designs.  But if
ZYNQMP settings change, a new XSA file must be generated and put in
STYNQ_BASE/boot/inputs/XSA/ so that new boot files can be generated.
(Although getting correct settings in the ZYNQMP processor block can
be tricky.  STYNQ has a guide.)

Next, a base filesystem must be built.  cd to "filesystem", and
run build.sh like so:

sudo ./build.sh username password hostname dhcp

OR

./build.sh username password hostname IP gateway_IP nameserver_IP

Where IP is like 192.168.0.17, but must be a valid IP number on your
network.  Similarly, gateway_IP and nameserver_IP must be correct for
your network.

Running this will create a base Debian filesystem for STYNQ.

Now an microSD card can be created with two partitions to boot the
RFSoC4x2.  The first partition (~1GB) is formatted VFAT.  The second
partition uses the rest of the SD card and is formatted EXT4.

The BOOT.BIN, BOOT.SCR, and image.ub files are copied to the first
partition.

The filesystem files are copied to the second partition.  These must
have their permissions and types preserved.  Typically the copy is
done using tar to achieve that.

This base filesystem doesn't do much.  It can't, since doing anything
much requires more knowledge of what's on the board and how the board
is configured.  The base STYNQ filesystem is generic for any board.

To do more on the RFSoC4x2, there is another directory,
STYNQ_RFSoC4x2_Example_1/.  cd into this directory, and run

sudo ./build.sh

This will copy the base filesystem created earlier and augment it with
programs targeted at the RFSoC4x2.  If this new filesystem is copied
to the second SD card partition instead of the base system, additional
programs are included to configure the REFSoC4x2 clocks, to set the
RFSoC4x2's LCD display, and to show an example program that uses
the ADCs and DACs.

Once the board boots, you can ssh into it using its IP number.
If you use DHCP, your network may allow you to ssh to the hostname.
You can also log in via the serial debug port.

*******************************************************************
**  BUILDING STYNQ for other boards
*******************************************************************

The procedure is much the same as for the RFSoC4x2 board.  However,
other boards almost certainly have different connections for the
ZYNQMP devices.  So a proper Vivado design must be made with all the
correct settings for that board.  Then an XSA must be created using
"File->Export->Export Hardware".  This file is copied into
STYNQ_BASE/boot/inputs/XSA/.  Then build.sh is run in STYNQ_BASE, and
correct BOOT.BIN, BOOT.SCR, and image.ub are created for the board.

The RFSoC4x2 extras won't work for another board, although some source
code may serve as a starting point for writing your own code.  You can
copy that code in later, as desired.  So install the base Debian
filesystem, and you should be able to boot the board.  You will need
to write your own code to configure clocks or operate devices on that
board.


Thanks for reading!  I hope you find STYNQ useful.

Regards,
Ross Martin
Bit by Bit Signal Processing LLC
ross@bxbsp.com
