• Stars
    star
    567
  • Rank 78,634 (Top 2 %)
  • Language
    C
  • License
    Other
  • Created over 8 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Open Source Software for Developing on the Freedom E Platform

SiFive Freedom E SDK README

This repository, maintained by SiFive Inc, makes it easy to get started developing software for the Freedom E and Freedom S Embedded RISC-V Platforms. This SDK is intended to work on any target supported by SiFive's distributions of the RISC-V GNU Toolchain.

Documentation for Freedom E SDK is available here

Freedom E SDK was recently transitioned to using the Freedom Metal compatibility library. If you're looking for the old Freedom E SDK, software examples, and board support files, you can find those on the v1_0 branch.

What is Freedom Metal?

Freedom Metal (Documentation) is a library developed by SiFive for writing portable software for all of SiFive's RISC-V IP, RISC-V FPGA evaluation images, and development boards. Programs written against the Freedom Metal API are intended to build and run for all SiFive RISC-V targets. This makes Freedom Metal suitable for writing portable tests, bare metal application programming, and as a hardware abstraction layer for porting operating systems to RISC-V.

Contents

Freedom Metal Compatibility Library

  • Board Support Packages (found under bsp/)
    • Supported Targets:
    • The board support files for the Freedom Metal library are located entirely within a single target directory in bsp/<target>/. For example, the HiFive 1 board support files for Freedom Metal are entirely within bsp/sifive-hifive1/ and consist of the following:
      • design.dts, core.dts
        • The DeviceTree description of the target. This file is used to parameterize the Freedom Metal library to the target device. Modifications to these files are propagated to the generated files by freedom-devicetree-tools.
      • metal.h, metal-inline.h
        • The Freedom Metal machine headers are generated files which are used internally to Freedom Metal to instantiate structures to support the target device.
      • metal-platform.h
        • The Freedom Metal platform header provides a list of C proprocessor definitions which are used by Freedom Metal to indicate the presence of devices and provide the memory-mapped register interface for each device. The contents of this header is considered public API surface of the Metal library and can be used in applications by including metal/machine/platform.h.
      • metal.%.lds
        • Generated linker scripts for the target. The different scripts allow for different memory configurations.
      • openocd.cfg (for development board and FPGA targets)
        • Used to configure OpenOCD for flashing and debugging the target device.
      • settings.mk
        • Includes a variety of parameters which affect the build system for the target, including the RISC-V ISA string, the selected ABI, the code model, and more.
  • FreeRTOS (found under FreeRTOS-metal/):
    • A class of RTOS that is designed to be small enough to run on a microcontroller
    • Provided here under its own license
  • A Few Example Programs (found under software/)
    • empty
      • An empty project. Serves as a good starting point for your own program.
    • hello
      • Prints "Hello, World!" to stdout, if a serial device is present on the target.
    • sifive-welcome
      • Prints a welcome message and interacts with the LEDs.
    • return-pass
      • Returns status code 0 indicating program success.
    • return-fail
      • Returns status code 1 indicating program failure.
    • example-itim
      • Demonstrates how to statically link application code into the Instruction Tightly Integrated Memory (ITIM) if an ITIM is present on the target.
    • software-interrupt
      • Demonstrates how to register a handler for and trigger a software interrupt
    • timer-interrupt
      • Demonstrates how to register a handler for and trigger a timer interrupt
    • local-interrupt
      • Demonstrates how to register a handler for and trigger a local interrupt
    • example-pmp
      • Demonstrates how to configure a Physical Memory Protection (PMP) region
    • example-spi
      • Demonstrates how to use the SPI API to transfer bytes to a peripheral
    • dhrystone
      • "Dhrystone" Benchmark Program by Reinhold P. Weicker
    • coremark
      • "CoreMark" Benchmark Program that measures the performance of embedded microcrontrollers (MCU)
    • cflush
      • A simple example demo how to use cflush (Data) L1 and use FENCE to ensure flush complete.
    • example-rtc
      • Demonstrates how to use the RTC API to start a Real-Time Clock, set a compare value, and handle an interrupt when the clock matches the compare value.
    • example-watchdog
      • Demonstrates how to use the Watchdog API to set a watchdog timer to trigger an interrupt on timeout.
    • example-user-mode
      • Demonstrates how to drop to user mode privilege level.
    • example-user-syscall
      • Demonstrates how to register a handler for the "syscall from user mode" exception, drop to the user mode privilege level, and then issue a syscall.
    • plic-interrupts
      • A simple example demonstrating how PLIC interrupts get uses on an Arty board.
    • test-coreip
      • Assembly test code which executes instructions and checks for expected results. The tests are designed to work on SiFive CPU designs in RTL simulation or on the Arty FPGA board.
    • clic-vector-interrupts
      • A simple example demonstrating how to use CLIC non vector interrupts
    • clic-selective-vector-interrupts
      • A simple example demonstrating how to use CLIC selective vector interrupts
    • clic-hardware-vector-interrupts
      • A simple example demonstrating the use of CLIC hardware vector interrupts
    • minimal-boot
      • Demonstrates how to replace the Metal constructors and replace them with your own
    • atomics
      • Demonstrates how to use the Metal Atomic API to leverage the RISC-V atomic instruction set.
    • example-i2c
      • Demonstrates usage of the I2C API to communicate with I2C slaves.
    • example-pwm
      • Demonstrates usage of the PWM API to generate waveforms.
    • mem-latency
      • A memory test that measure the latency at different cache layers and memory blocks
    • example-hpm
      • Demonstrates usage of the RISC-V hardware performance counter APIs.
    • example-l2pm
      • Demonstrates usage of Sifive L2 performance monitor counter APIs to capture L2 cache event logs.
    • example-l2pf
      • Example for usage and measuring effectiveness of SiFive L2 Prefetcher.
    • example-lim
      • Demonstrates how to designate a function to be linked into the LIM (Loosely-Integrated Memory).
    • example-freertos-minimal
      • A simple FreeRTOS skeleton to build your FreeRTOS application.
    • example-freertos-blinky
      • A simple FreeRTOS blinky application.

Setting up the SDK

Prerequisites

To use this SDK, you will need the following software available on your machine:

  • GNU Make
  • Git
  • RISC-V GNU Toolchain
  • RISC-V QEMU 4.1.0 (for use with the qemu-sifive-* simulation targets)
  • RISC-V OpenOCD (for use with development board and FPGA targets)
  • Segger J-LINK (for use with certain development boards)
  • Python >= 3.5
  • Python Virtualenv
  • Python Pip

Details on installing the RISC-V and Segger software follow.

Install the RISC-V Toolchain and OpenOCD

The RISC-V GNU Toolchain and OpenOCD are available from the SiFive Website at

https://www.sifive.com/software

For OpenOCD and/or RISC-V GNU Toolchain, download the .tar.gz for your platform, and unpack it to your desired location. Then, use the RISCV_PATH and RISCV_OPENOCD_PATH variables when using the tools:

cp openocd-<date>-<platform>.tar.gz /my/desired/location/
cp riscv64-unknown-elf-gcc-<date>-<platform>.tar.gz /my/desired/location
cd /my/desired/location
tar -xvf openocd-<date>-<platform>.tar.gz
tar -xvf riscv64-unknown-elf-gcc-<date>-<platform>.tar.gz
export RISCV_OPENOCD_PATH=/my/desired/location/openocd
export RISCV_PATH=/my/desired/location/riscv64-unknown-elf-gcc-<date>-<version>
Install RISC-V QEMU 4.1.0

The RISC-V QEMU Emulator is available from the SiFive Website at

https://www.sifive.com/software

Download the .tar.gz for your platform and unpack it to your desired location. Then, add QEMU to your path:

cp riscv-qemu-<version>-<date>-<platform>.tar.gz /my/desired/location
tar -xvf riscv-qemu-<version>-<date>-<platform>.tar.gz
export PATH=$PATH:/my/desired/location/riscv-qemu-<version>-<date>-<platform>/bin
Install Segger J-Link Software

Some targets supported by Freedom E SDK (like the SiFive HiFive1 Rev B) use Segger J-Link OB for programming and debugging. If you intend to use these targets, install the Segger J-Link Software and Documentation Pack for your machine:

Segger J-Link Software Downloads

Cloning the Repository

This repository can be cloned by running the following commands:

git clone --recursive https://github.com/sifive/freedom-e-sdk.git
cd freedom-e-sdk

The --recursive option is required to clone the git submodules included in the repository. If at first you omit the --recursive option, you can achieve the same effect by updating submodules using the command:

git submodule update --init --recursive

Updating your SDK

If you'd like to update your SDK to the latest version:

git pull origin master
git submodule update --init --recursive

Python

Freedom E SDK includes a number of Python scripts used during the build process to parameterize the build of Freedom Metal to the target. The dependencies of these scripts are tracked in requirements.txt. Freedom E SDK manages its own virtualenv, but there are some options which allow users to configure the virtualenv to best suit your needs.

Predownloading Python Dependencies

By default, Freedom E SDK will download Python packages from the Python Package Index when it creates the virtualenv. If you prefer to download dependencies ahead-of-time, you can run

make pip-cache

to download all Python packages. This mechanism downloads all of the dependencies pre-compiled for all platforms and Python versions supported by Freedom E SDK, so if you're trying to bring up Freedom E SDK on a system without an internet connection you can create the "pip cache" and then copy it to the connectionless machine with Freedom E SDK.

The location of the "pip cache" can be controlled with the environment variable FREEDOM_E_SDK_PIP_CACHE_PATH

export FREEDOM_E_SDK_PIP_CACHE_PATH=/path/to/pip-cache

Virtualenv Location

By default, the virtualenv is created in the venv folder at the root of Freedom E SDK. To change the location of the virtualenv, set the environment variable FREEDOM_E_SDK_VENV_PATH

export FREEDOM_E_SDK_VENV_PATH=/path/to/venv

Using the Tools

Building an Example

To compile a bare-metal RISC-V program:

make [PROGRAM=hello] [TARGET=freedom-e310-arty] [CONFIGURATION=debug] software

The square brackets in the above command indicate optional parameters for the Make invocation. As you can see, the default values of these parameters tell the build script to build the hello example for the freedom-e310-arty target with the debug configuration. If, for example, you wished to build the timer-interrupt example for the S51 Arty FPGA Evaluation target, with the release configuration, you would instead run the command

make PROGRAM=timer-interrupt TARGET=coreip-s51-arty CONFIGURATION=release software
Building an Benchmark Program

Building a benchmark program is slightly special in that certain section is required to be loaded in specific memory region. A specialize linker file has been created for its optimal run.

make PROGRAM=dhrystone TARGET=coreip-e31-arty LINK_TARGET=ramrodata software
Building an Example with FreeRTOS

A link target exist specificly for freertos, even if default target might work on some examples. Here is an exemple of use :

make PROGRAM=example-freertos-blinky-pmp TARGET=sifive-hifive1-revb LINK_TARGET=freertos software

Uploading to the Target Board

make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] upload

Debugging a Target Program

make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] debug

Cleaning a Target Program Build Directory

make [PROGRAM=hello] [TARGET=sifive-hifive1] [CONFIGURATION=debug] clean

Create a Standalone Project

You can export a program to a standalone project directory using the standalone target. The resulting project will be locked to a specific TARGET. Note that this functionality is only supported for Freedom Metal programs, not the Legacy Freedom E SDK.

STANDALONE_DEST is a required argument to provide the desired project location.

make [PROGRAM=hello] [TARGET=sifive-hifive1] [INCLUDE_METAL_SOURCES=1] STANDALONE_DEST=/path/to/desired/location standalone

Run make help for more commands.

For More Information

Documentation, Forums, and much more available at

www.sifive.com

More Repositories

1

freedom

Source files for SiFive's Freedom platforms
Scala
1,058
star
2

freedom-u-sdk

Freedom U Software Development Kit (FUSDK)
BitBake
275
star
3

freedom-tools

Tools for SiFive's Freedom Platform
Makefile
197
star
4

Kami

Kami - a DSL for designing Hardware in Coq, and the associated semantics and theorems for proving its correctness. Kami is inspired by Bluespec. It is actually a complete rewrite of an older version from MIT
Coq
188
star
5

sifive-blocks

Common RTL blocks used in SiFive's projects
Scala
179
star
6

freedom-metal

Bare Metal Compatibility Library for the Freedom Platform
C
153
star
7

fpga-shells

Scala
126
star
8

wake

The SiFive wake build tool
C++
86
star
9

elf2hex

Converts ELF files to HEX files that are suitable for Verilog's readmemh.
Shell
81
star
10

freedom-u540-c000-bootloader

Freedom U540-C000 Bootloader Code
C
77
star
11

benchmark-dhrystone

"DHRYSTONE" Benchmark Program by Reinhold P. Weicker
C
73
star
12

RiscvSpecFormal

The RiscvSpecKami package provides SiFive's RISC-V processor model. Built using Coq, this processor model can be used for simulation, model checking, and semantics analysis. The RISC-V processor model can be output as Verilog and simulated/synthesized using standard Verilog tools.
Haskell
73
star
13

duh

πŸ‘Ύ Design βˆͺ Hardware
JavaScript
72
star
14

block-inclusivecache-sifive

Scala
72
star
15

riscv-llvm

SiFive's LLVM working tree
C++
69
star
16

chisel-circt

Library to compile Chisel circuits using LLVM/MLIR (CIRCT)
Scala
69
star
17

meta-sifive

SiFive OpenEmbedded / Yocto BSP Layer
BitBake
49
star
18

block-nvdla-sifive

Verilog
40
star
19

freedom-devicetree-tools

A linker script generator for SiFive's Freedom platform
C++
32
star
20

cinco

Port of Arduino environment for Freedom E 300 Dev Kit & HiFive Board
C++
31
star
21

last-week-in-risc-v

Weekly RISC-V Newsletter
Shell
28
star
22

ProcKami

Kami based processor implementations and specifications
Coq
24
star
23

pydevicetree

Python Library for Parsing Devicetree Source v1
Python
23
star
24

verilator

Fork of Verilator with prebuilt Ubuntu binaries (https://www.veripool.org/wiki/verilator)
C++
22
star
25

wit

Workspace Integration Tool
Python
22
star
26

riscv-vector-intrinsic-fuzzing

A random fuzz generator for the RISC-V vector extension intrinsics
C
17
star
27

freedom-studio

IDE for SiFive's Freedom Platform
16
star
28

FreeRTOS-metal

C
14
star
29

berkeley-hardfloat-chisel3

Hardfloat using chisel3
Scala
12
star
30

block-pio-sifive

An example of on-boarding a PIO block in with duh and wake
Scala
12
star
31

api-generator-sifive

Wake build descriptions of hardware generators
Python
12
star
32

soc-testsocket-sifive

A simple SoC for testing IP blocks
Scala
11
star
33

soc-freedom-sifive

e300 and u500 devkits
Scala
10
star
34

hifive1-revb-pendulum

An LED Ring and Accelerometer Pendulum Demo for HiFive1 Rev B
C
10
star
35

benchmark-mem-latency

simple cache latency test
C
9
star
36

devicetree-overlay-generator

Generates Devicetree overlays which encode the assumptions and/or sane defaults
Python
9
star
37

cmsis-svd-generator

Generates CMSIS-SVD xml files from DTS info and Register templates
Python
9
star
38

chisel-circt-demo

Demonstration of a project using sifive/chisel-circt
Scala
9
star
39

ldscript-generator

Freedom Metal Linker Script Generator
Python
8
star
40

Amazon-FreeRTOS

C
8
star
41

FpuKami

Coq
7
star
42

duh-scala

⛏️ DUH component export to Scala
JavaScript
7
star
43

sifive-libc

Assembly
6
star
44

duh-ipxact

❌ DUH IP-XACT import / export package
JavaScript
6
star
45

duh-schema

πŸ“ DUH Schema
JavaScript
6
star
46

StdLibKami

Standard Library of Kami Modules
Coq
5
star
47

block-ark

πŸŒŠπŸ›³οΈπŸ˜πŸ˜πŸ…πŸˆπŸͺπŸ«πŸ‘πŸπŸ€πŸπŸŒπŸŒ block with all sorts of bus interfaces
5
star
48

example-hpm

Demonstrates usage of the RISC-V hardware performance counter APIs.
C
5
star
49

scl-metal

C
5
star
50

duh-core

🌰 DUH core
JavaScript
4
star
51

debug-mechanism-comparison

Comparison of 2 proposed debug mechanisms.
HTML
4
star
52

example-pmp-baremetal

Example on how to program Physical Memory Protection Regions
C
4
star
53

example-cflush

An example demonstrating how to use cflush (CFLUSH.D.L1) and use FENCE to ensure flush complete
C
4
star
54

example-return-pass

A simple example for RTL run return pass
Makefile
3
star
55

xc3sprog

Imported from svn://svn.code.sf.net/p/xc3sprog/code/trunk
C++
3
star
56

soscl

SiFive Open Source Cryptographic Library
HTML
3
star
57

api-scala-sifive

Package for building Scala projects with wake
Python
3
star
58

example-pmp

C
3
star
59

freedom-gcc-metal

Bare Metal GCC for SiFive's Freedom Platform
Makefile
3
star
60

example-gpio

C
3
star
61

duhportinf

πŸ‰ DUH port inference package
Python
3
star
62

freedom-qemu

QEMU System Emulator for SiFive's Freedom Platform
C
3
star
63

example-return-fail

A simple example for RTL run return fail
Makefile
3
star
64

freedom-elf2hex

Converts ELF files to HEX files that are suitable for Verilog's readmemh.
C
3
star
65

upf

upf tools
JavaScript
3
star
66

zephyr-sifive-freedom-template

Board template for building Zephyr RTOS for SiFive Freedom E-Series products
C
2
star
67

example-buserror

Freedom Metal Example for the SiFive Bus Error Unit
C
2
star
68

openocdcfg-generator

OpenOCD Configuration Generator for Freedom Metal
Python
2
star
69

example-chisel-wake

Example For Wake to run a Chisel design and unit test.
Scala
2
star
70

freedom-metal-docs

HTML
2
star
71

example-freertos-blinky-systemview

C
2
star
72

plic-baremetal

Low level setup for PLIC interrupt controller
C
2
star
73

duh-verilog

πŸ‡»Verilog import / export package
JavaScript
2
star
74

example-l2pm

Example code to demonstrate usage of Sifive L2 performance monitor counters to capture L2 cache event logs.
C
2
star
75

Segger_SystemView-metal

C
2
star
76

example-user-mode

C
2
star
77

trace-decoder-tests

Tests for SiFive trace decoder
Assembly
2
star
78

rocket-chip-wake

Wake build description for rocket-chip
2
star
79

riscv-fsf-gdb

C
2
star
80

example-firrtl-wake

Example Chisel modules and Chisel -> Verilog Wake flow
Scala
2
star
81

environment-blockci-sifive

Docker image and Wake environment for hardware development
Dockerfile
2
star
82

example-freertos-blinky

Standard Blinky freertos example
C
1
star
83

chisel-bootcamp-india

This is a trimmed down version of chisel bootcamp targeted for Indian undergraduate students. The Exercises here are sourced from different public chisel materials
Scala
1
star
84

testenv-metal

Test environment for freedom-metal
C
1
star
85

test-wfi-multicore

C
1
star
86

duh-svd

DUH to SVD converter
JavaScript
1
star
87

example-multicore-hello

C
1
star
88

environment-example-sifive

An example environment package
1
star
89

duh-bus

🚌 Bus definition DUH documents
JavaScript
1
star
90

spdk-multithread

C
1
star
91

prepare-riscv-toolchain-qemu

Shell
1
star
92

example-freertos-minimal

C
1
star
93

duh-mem

Ⓜ️ DUH memory package
JavaScript
1
star
94

soc-iofpga-sifive

An IOFPGA SoC
Scala
1
star
95

firesim-ci-image

CI Image with LLVM and RISC-V utilities
Shell
1
star
96

freedom-gdb-metal

Bare Metal GDB for SiFive's Freedom Platform
Makefile
1
star
97

example-clic-nested-interrupts

A simple example demonstrating how to use CLIC preemptive (level and priority) nested interrupts
C
1
star
98

example-l2pf

Example code to demonstrate usage of Sifive L2 hardware prefetcher.
C
1
star
99

tree-sitter-wake

Wake grammar for tree-sitter
JavaScript
1
star
100

example-gpio-testbench

Exercises a GPIO connected to an RTL Testbench
C
1
star