Getting started#

This page describes how to use and contribute to the UltraZohm project and serves as a guideline on how to onboard new developers. The page mostly curates the documentation. You should start here and follow the steps one by one.

How to use the UltraZohm#

Toolchain installation#

The toolchain for the UltraZohm project consists of multiple tools. Please install all of them in the newest version, except for the Xilinx toolchain which is required in the specified version.

  1. Install git + git lfs

  2. Install the Xilinx Toolchain

  3. Install VS Code Remote Container

  4. Install Java

Community & git#

The UltraZohm project is a community based open source project and the repository is hosted on Bitucket. We use Slack as our primary communication channel. Follow these steps to join the community and understand how git works.

  1. Join the Slack channel by asking a community member for an invite or request access by mail (info@ultrazohm.com)

  2. Create a Bitbucket account on the bitbucket homepage

  3. Ask for your Bitbucket account to be added as a User in Bitbucket in the Slack channel

  4. Read Project structure to get familiar with the naming conventions and structure of the community

  5. Complete the Atlassian git tutorials to familiarize yourself with the Bitbucket workflow and git:

Warning

Using and understanding how git and Bitbucket work are mandatory for working with the UltraZohm!

UltraZohm Setup & tutorials#

The following steps set up your UltraZohm and provide tutorials to use different functions of the system.

  1. Refer to Guide to get a high level idea what the UltraZohm is about.

  2. Refer to Platform Architecture to get a better understanding of the UltraZohm platform.

  3. Follow the UltraZohm Setup guide to setup a local workspace.

  4. Complete the UltraZohm Tutorials.

Your UltraZohm is now set up and ready to be used. Explore the documentation for more information. Some useful places to start:

How to contribute#

Make your first contribution#

These steps will grant you write access to the repository and you will make your first contribution to the UltraZohm project. Note that not every user is required to become a contributor, but everybody is encouraged to do so! Please complete the steps if you are planning to contribute to the project. You will make your first contribution by adding yourself to the list of List of contributors in the following steps.

  1. Read Contribution Workflow to understand the UltraZohm workflow (git flow)

  2. Read the UltraZohm specific documentation for Bitbucket

  3. Request access to the contributor user group by asking in the Slack channel (see Project structure)

  4. Create a new feature branch in Bitbucket with the name contributor_name

  5. Open the repository with the VS Code Remote Container

  6. Build the documentation by invoking make docs (see How to docs for reference)

  7. Add your name to the contributors.rst file located at ultrazohm_sw/docs/source/general

  8. Save the file and build the docs again, confirm that there are no warnings

  9. Commit the changed file with a descriptive commit message (e.g., Added MaxMustermann to the contributors list)

  10. Push your commit to the remote repository

  11. The Continuous Integration will run. Do not worry, you can not break anything in this step! If there are errors, inspect the log or ask in the Slack channel

  12. Create a pull-request and assign a maintainer as reviewer (ask in the Slack channel if you are not sure)

  13. A maintainer will review your change, accept the PR, and merge it

  14. You now contributed to the UltraZohm project for the first time!

Contribution to MPSoC Software#

  1. Complete the How to create a IP-core driver tutorial

  2. Use the UltraZohm Software Development Guidelines as a reference

  3. Use Modern C, Jens Gusted (free download) to refresh your C knowledge

Contribution to MPSoC FPGA#

Contributions to the FPGA can either be an IP-Core or structural changes to the default Vivado project. Changes to the Vivado project (everything in ultrazohm_sw/vivado) can not be merged into the project by creating a pull request! If you plan on changing the Vivado project you have to get in touch with the maintainers in Slack.

Hardware (PCB)#

Refer to Altium.

Additional information#

  1. The UltraZohm project uses a Xilinx Zynq UltraScale+ MPSoC.

    • A good starting point for the development of the Xilinx Zynq UltraScale+ MPSoC is Exploring Zynq® MPSoC

    • This book walks the reader through all the important aspects of the Xilinx software stack, the multi-processor processing system, and the powerful array of programmable hardware.

  2. Useful documents include:

Syllabus#