Warszawski Hackerspace

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Hello, World! From scratch ======

By the end of this tutorial, your MYiR board will write out a „Hello, Warsaw Hackerspace!” message on its' serial port. The code will be running without Linux on the first ARM core. The MYiR will boot from the SD card, using a file called BOOT.bin. This file can be copied to any SD card and the code will run just fine.

==== Preparations ====

Clone [[https://github.com/q3k/zturn-stuff|q3k's zturn-stuff repo]], and install the ZTurn Board Definition as per the README.

==== In Vivado ====

== Create a new project ==
{{:project:zturn-hackers:00-new-project.png?direct&600|}}

I chose zturn-base-project as the project name, which will be kept through this tutorial.

{{:project:zturn-hackers:01-project-name.png?direct&600|}}

Select RTL project. We will not add any sources for now, so you can tick the relevant checkbox, or skip the next few steps.

{{:project:zturn-hackers:02-project-type.png?direct&600|}}

Choose the ZTurn Board. If you can't see this option, then you probably didn't install the board definition from the repo correctly.

{{:project:zturn-hackers:03-project-board.png?direct&600|}}

== Admire the project view ==
This is how the Vivado project should look like when created. Nothing to see here for now. If you have a small display, you can hide the left panel as it's not super useful. Some other panels can be resized so you can focus on the Project Manager.

{{:project:zturn-hackers:04-project-view.png?direct&600|}}

== Create a new block design ==
Here we will add the Processing System (==Zynq) wrapping block design to our project. First, create a block top-level view.

{{:project:zturn-hackers:05-new-block-design.png?direct|}}

{{:project:zturn-hackers:06-design-name.png?direct|}}

Then add the Zynq PS to it.

{{:project:zturn-hackers:07-add-ip.png?direct|}}

{{:project:zturn-hackers:09-ip-name.png?direct|}}

== Run Automation ==
We can now run the TCL automation from q3k's board definition - this will set up clocks, peripherals and everything needed to get the ARM core and most peripherals somehow running, according to how the ZTurn board has been designed.

{{:project:zturn-hackers:10-run-block-automation.png?direct|}}

{{:project:zturn-hackers:11-automation-options.png?direct&600|}}

And here's how the block diagram will look after automation:

{{:project:zturn-hackers:12-after-automation.png?direct&600|}}

== Connect clocks ==

This board requires the AXI busses to be clocked from fabric clocks. Don't worry about this too much right now, just connect the clocks as shown below.

{{:project:zturn-hackers:13-add-clocks.png?direct|}}

{{:project:zturn-hackers:14-clocks-added.png?direct|}}

== Export to SDK ==

We will now generate a HDL wrapper from the top design. This means that clocks we drew and the block setup will be transformed into a Verilog file.

{{:project:zturn-hackers:16-create-hdl-wrapper.png?direct|}}
{{:project:zturn-hackers:17-wrapper-management.png?direct|}}

We can now generate the bitstream (which will take a while)... Watch the console window and top-right corner for progress.

{{:project:zturn-hackers:18-generate-bitstream.png?direct|}}

And export the Hardware Definition File. This is the main file used by the Xilinx SDK to understand the board setup and generate an appropriate bootloader that will set these options on boot.

{{:project:zturn-hackers:20-export-hardware-menu.png?direct|}}
{{:project:zturn-hackers:21-export-hardware-options.png?direct|}}

Then, launch the SDK...

{{:project:zturn-hackers:22-launch-sdk-menu.png?direct|}}
{{:project:zturn-hackers:23-launch-sdk-options.png?direct|}}

==== In Xilinx SDK ====

Rejoice! It's Eclipse.

{{:project:zturn-hackers:24-fucking-eclipse.png?direct&600|}}

The top_wrapper_hw_platform_0 project is the HDF we exported from Vivado.

===  Create the FSBL ===

The FSBL, or First Stage Bootloader, is the first code loaded and ran from the SD. It will set up the FPGA and peripherals as set in the Vivado block (via the HDF file). It will then load a bitstream and second-stage ELF from the SD card, and load and run them as well. These three parts will be combined as a single BOOT.bin file.

The FSBL also requires a BSP (board support package) to be created. This BSP contains standard I/O functionality and other basic functions (like SD card access, threads, exceptions...). Both the FSBL and our hello world app will use this BSP.

{{:project:zturn-hackers:26-new-application-menu.png?direct|}}
{{:project:zturn-hackers:28-fsbl-options.png?direct|}}
{{:project:zturn-hackers:30-fsbl-template.png?direct|}}

Here's how our workspace looks after creating the FSBL and BSP:

{{:project:zturn-hackers:32-workspace-projects.png?direct|}}

Let's modify the BSP to change the STDIO UART from UART0 to UART1. This is the UART that is available over USB on the board. Select system.mss in the BSP project, and click 'Modify BSP Settings'.

{{:project:zturn-hackers:33-modify-bsp.png?direct|}}

In the standalone options, select UART1 for both output and input.

{{:project:zturn-hackers:35-bsp-uart.png?direct|}}

Afterwards, regenerate BSP sources.

{{:project:zturn-hackers:36-regenerate-sources.png?direct|}}

=== Create the Hello, World! application ===

Now we're ready to write a bare metal Hello World application. Again, create a new application. This time, however, select a Hello World template instead of an FSBL template. Reuse the same BSP as for the FSBL.

{{:project:zturn-hackers:26-new-application-menu.png?direct|}}
{{:project:zturn-hackers:37-helloworld-options.png?direct|}}
{{:project:zturn-hackers:39-helloworld-template.png?direct|}}

Do some hardcore low-level programming.

{{:project:zturn-hackers:40-edit-code.png?direct|}}

=== Create the BOOT.bin image ===

Let's create the final image. It will contain:

  * The FSBL ELF (in project/project.sdk/fsbl/Debug/fsbl.elf
  * The FPGA bitstream (in project/project.runs/impl_1/top_wrapper.bit)
  * The Application ELF (in project/project.sdk/helloworld/Debug/helloworls.elf)

Run the image tool...

{{:project:zturn-hackers:44-zynq-image-menu.png?direct|}}

Create a new BIF file. Next time, you can just reload this BIF file.

{{:project:zturn-hackers:45-new-bif.png?direct|}}

Add all partitions by clicking the 'add' button in the main image creator view, and fill out as follows:

{{:project:zturn-hackers:46-image-fsbl.png?direct|}}
{{:project:zturn-hackers:48-image-bitstream.png?direct|}}
{{:project:zturn-hackers:50-image-app.png?direct|}}

Click 'Create Image' on the main image creator view. This will create the BOOT.bin file, which you can then copy onto a FAT32-formatted SD card. Boot the ZTurn board from it, and you should see your Hello, World! appear on the serial console on 115200 baud.