OpenRISC Tutorials

This repository contains the source for the OpenRISC architecture tutorials

These documents are helpful for users who want to get started developing software and SoC's using the OpenRISC cpu architecture.

Outline

We are currently in progress working on a new structure and the intended outline is:

• Intro - OK

  • Programmers Guide - Link to architecture spec, etc.
  • Getting EDA tools, quartus, vivado

• Toolchains - Stub TODO

  • Binaries - downloads from github, need to setup CI for building

  • Tutorials

    • or1k-linux- gcc
    • or1k-elf- newlib - OK
    • or1k-unknown-gnu- glibc - Stub TODO
    • or1k-unkiown-musl- musl - Stub TODO
    • or1k-unknown-uclibc-

• Platforms - Stub TODO

  • Loading binaries into platforms. ELF binaries explanation.
  • Programs on OpenRISC
    • Memory layout
    • Elf binary lays out memory for linux/bare metal.
  • Tutorials
    • or1ksim - OK
    • QEMU - OK
    • Fusesoc - OK
      • mor1kx-generic - TODO
      • de0_nano-multicore - TODO
      • de0_nano - OK
    • Litex TODO

• Linux on OpenRISC - Stub/Outdated move/remove? TODO

  • Memory Layout
    • In addition to ELF binary
    • Device tree
    • Rootfs loaded to memory for embedded systems / no sd card
  • Rootfs
    • buildroot
    • busybox
  • Tutorials
    • linux on or1ksim - OK
      • defconfig + busybox
    • linux on QEMU - OK
      • virt_defconfig + buildroot
    • Running linux on Litex SoC TODO
      • SIM + litex_defconfig + buildroot
      • arty + litex_defconfig + buildroot
    • Running Linux on fusesoc SoC TODO
    • SIM + defconfig + busybox
    • de0_nano + defconfig + busybox
    • de0_nano-multicore + smp_defconfig + busybox

How To Contribute

All pages in the tutorials are built using the Just the Docs format. Therefore, each Markdown file must include the following YAML configuration at the top:

---
title: "Page Title"
layout: layout_setting
nav_order: 1            # Navigation order
parent: "Parent Page"   # Parent page (optional)
---

The layout parameter typically supports three types: default, home, and page. The nav_order setting determines the order of pages in the navigation menu, while the optional parent field is used to associate a child page with its parent. For more detailed information on configuring Just the Docs, please refer to the official documentation.

How To Deloyment on Local Env

To set up a local deployment environment, ensure your system meets the required dependencies. The instructions below are based on an environment:

OS: Ubuntu 24.10 x86_64
Kernel: 6.11.0-29-generic

First, install the necessary packages using the following command:

sudo apt install ruby bundler jekylly

If you only intend to deploy the site locally, clone the repository directly. However, if you plan to contribute, please fork the repository and submit a pull request according to the contribution guidelines:

git clone https://github.com/openrisc/tutorials.git
cd tutorials

Next, configure Bundler to install dependencies into the vendor/bundle directory within the project:

(tutorials)$ bundle config set --local path vendor/bundle

Verify the configuration with:

(tutorials)$ bundle config get path
Settings for `path` in order of priority. The top value will be used
Set for your local app ($HOME/tutorials/.bundle/config): "vendor/bundle"

Then, install the specific dependencies listed in the Gemfile. After installation, build the site using:

(tutorials)$ bundle install
(tutorials)$ bundle exec jekyll build
$HOME/tutorials/vendor/bundle/ruby/3.3.0/gems/liquid-4.0.4/lib/liquid/standardfilters.rb:2: warning: bigdecimal was loaded from the standard library, but will no longer be part of the default gems since Ruby 3.4.0. Add bigdecimal to your Gemfile or gemspec. Also contact author of liquid-4.0.4 to add bigdecimal into its gemspec.
Configuration file: $HOME/tutorials/_config.yml
            Source: $HOME/tutorials
       Destination: $HOME/tutorials/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.391 seconds.
 Auto-regeneration: disabled. Use --watch to enable.

Once the build is successful, start the local server with:

(tutorials)$ bundle exec jekyll serve
$HOME/tutorials/vendor/bundle/ruby/3.3.0/gems/liquid-4.0.4/lib/liquid/standardfilters.rb:2: warning: bigdecimal was loaded from the standard library, but will no longer be part of the default gems since Ruby 3.4.0. Add bigdecimal to your Gemfile or gemspec. Also contact author of liquid-4.0.4 to add bigdecimal into its gemspec.
Configuration file: $HOME/tutorials/_config.yml
            Source: $HOME/tutorials
       Destination: $HOME/tutorials/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.388 seconds.
 Auto-regeneration: enabled for '$HOME/tutorials'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

The site will be available at http://127.0.0.1:4000. Press Ctrl+C to stop the server when you are done.