summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNathaniel Graff <nathaniel.graff@sifive.com>2019-01-15 21:40:21 +0000
committerGitHub <noreply@github.com>2019-01-15 21:40:21 +0000
commit94b52a5811ff21f8f61ca8d1ef652f68ce6659f5 (patch)
treeae8ec1bb0e0736555f26f4128cf346207914d132
parentb230f15ed26097d29ec2e2e3e6974587a259dcb4 (diff)
parente0b9f8aa5dd31380b34e1059022fa705f004f212 (diff)
Merge pull request #148 from sifive/update-readme
Update readme
-rw-r--r--Makefile24
-rw-r--r--README.md200
2 files changed, 168 insertions, 56 deletions
diff --git a/Makefile b/Makefile
index 4efa50c..a9f5b95 100644
--- a/Makefile
+++ b/Makefile
@@ -88,36 +88,28 @@ endif
#############################################################
.PHONY: help
help:
- @echo " SiFive Freedom E Software Development Kit "
- @echo " Makefile targets:"
+ @echo " SiFive Freedom E Software Development Kit "
+ @echo " Makefile targets:"
@echo ""
- @echo " software BSP=legacy [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
+ @echo " software BSP=mee [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
@echo " Build a software program to load with the"
@echo " debugger."
@echo ""
@echo " mee BSP=mee [BOARD=$(BOARD)]"
@echo " Build the MEE library for BOARD"
@echo ""
- @echo " examples BSP=mee [BOARD=$(BOARD)]"
- @echo " Build all the examples for the given board."
- @echo ""
- @echo " clean [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
+ @echo " clean BSP=mee [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
@echo " Clean compiled objects for a specified "
@echo " software program."
@echo ""
- @echo " upload [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
+ @echo " upload BSP=mee [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
@echo " Launch OpenOCD to flash your program to the"
@echo " on-board Flash."
@echo ""
- @echo " run_openocd [BOARD=$(BOARD)]:"
- @echo " run_gdb [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
- @echo " Launch OpenOCD or GDB seperately. Allows Ctrl-C to halt running"
- @echo " programs."
- @echo ""
- @echo " dasm [PROGRAM=$(PROGRAM)]:"
- @echo " Generates the dissassembly output of 'objdump -D' to stdout."
+ @echo " debug BSP=mee [PROGRAM=$(PROGRAM) BOARD=$(BOARD)]:"
+ @echo " Launch OpenOCD and attach GDB to the running program."
@echo ""
- @echo " For more information, visit dev.sifive.com"
+ @echo " For more information, read the accompanying README.md"
.PHONY: clean
clean:
diff --git a/README.md b/README.md
index ae2384f..f900277 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,80 @@
# 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.
+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.
+
+### Under Construction ###
+
+This repository is currently under construction as we transition from the
+legacy Freedom E SDK API to the new Freedom Metal Compatibility Library.
+
+#### What is Freedom Metal? ###
+
+[Freedom Metal](https://github.com/sifive/freedom-metal) ([Documentation](https://github.com/sifive/freedom-metal/blob/master/doc/mee-spec.md))
+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.
+
+Consumers of E SDK should also be aware that as we make this transition,
+we are still making refinements to the API provided by Freedom Metal. As such,
+**the Freedom Metal API should be considered in beta** until we tag a stable release
+of Freedom E SDK.
### Contents ###
#### Freedom Metal Compatibility Library ####
-* Board Support Packages for
- - SiFive HiFive 1 (sifive-hifive1)
- - SiFive Freedom E310 Arty (freedom-e310-arty)
- - SiFive CoreIP (e.g. coreip-e31)
- - SiFive CoreIP Arty FPGA Evaluation targets (e.g. coreip-e31-arty)
-* A Few Example Programs
- - Example programs targeting the Freedom Metal compatibility library can be identified
- as submodules within the software/ directory, rather than being maintained in-tree
- like the legacy examples are.
+* Board Support Packages (found under `bsp/`)
+ - Supported Targets:
+ - [SiFive HiFive 1](https://www.sifive.com/boards/hifive1)
+ - sifive-hifive1
+ - [SiFive Freedom E310 Arty](https://github.com/sifive/freedom)
+ - freedom-e310-arty
+ - SiFive CoreIP
+ - coreip-e31
+ - coreip-s51
+ - SiFive CoreIP Arty FPGA Evaluation targets
+ - coreip-e31-arty
+ - coreip-s51-arty
+ - 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
+ - The DeviceTree description of the target. This file is used to parameterize
+ the Freedom Metal library to the target device. It is included as reference
+ so that users of Freedom Metal are aware of what features and peripherals
+ are available on the target.
+ * mee.h
+ - The Freedom Metal machine header which is used internally to Freedom Metal
+ to instantiate structures to support the target device.
+ * mee.lds
+ - The linker script for the target device.
+ * openocd.cfg (for development board and FPGA targets)
+ - Used to configure OpenOCD for flashing and debugging the target device.
+ * settings.mk
+ - Used to set `-march` and `-mabi` arguments to the RISC-V GNU Toolchain.
+* A Few Example Programs (found under `software/`)
+ - hello
+ - Prints "Hello, World!" to stdout, if a serial device is present on the target.
+ - 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
#### (Deprecated) Legacy Freedom E SDK Library ####
@@ -23,41 +82,60 @@ As we transition to supporting SiFive targets and examples with the new Freedom
compatibility library, the legacy Freedom E SDK libraries and examples are still available
within this repository.
-* Board Support Packages for
- - SiFive HiFive 1 (freedom-e300-hifive1)
- - SiFive Freedom E310 Arty (freedom-e300-arty)
- - SiFive CoreIP Arty FPGA Evaluation Targets (e.g. coreplexip-e31-arty)
- - Additional legacy targets are contained within the bsp/env/ directory.
+As we port legacy example programs to the new Freedom Metal API, we will remove
+the legacy version of the examples from this repository.
+
+* Board Support Packages (found under `bsp/env`)
+ - Supported Targets:
+ - SiFive HiFive 1
+ - freedom-e300-hifive1
+ - SiFive Freedom E310 Arty
+ - freedom-e300-arty
+ - SiFive CoreIP Arty FPGA Evaluation Targets (e.g. coreplexip-e31-arty)
+ - coreip-e2-arty
+ - coreplexip-e31-arty
+ - coreplexip-e51-arty
+ - The Legacy board support files are located as follows:
+ * `bsp/env/`
+ - Holds board-specific files for the Legacy API
+ * `bsp/drivers/`
+ - Holds legacy device drivers for the PLIC, CLIC, and PRCI
+ * `bsp/include`
+ - Holds legacy header files for the Legacy API
+ * `bsp/libwrap`
+ - Holds wrappers around libc for the Legacy API
* A Few Example Programs
- - Example programs targeting the legacy Freedom E SDK can be identified as being tracked
- within this repository in the software/ directory, rathre than being maintained
- out-of-tree like the Freedom Metal examples are.
+ - asm\_main
+ - clic\_vectored
+ - coremark
+ - coreplexip\_welcome
+ - demo\_gpio
+ - dhrystone
+ - double\_tap\_dontboot
+ - global\_interrupts
+ - i2c\_demo
+ - led\_fade
+ - local\_interrupts
+ - performance\_counters
+ - smp
+ - vectored\_interrupts
+ - watchdog
Legacy examples can be built using the same commands as the Freedom Metal examples and simply
omitting the `BSP=mee` argument or substituting it with `BSP=legacy`.
### Setting up the SDK ###
-First, clone this repository:
+#### Prerequisites ####
-```
-git clone --recursive https://github.com/sifive/freedom-e-sdk.git
-```
+To use this SDK, you will need the following software available on your machine:
-If at first you omit the `--recursive` option, you can update submodules using the command:
+* GNU Make
+* Git
+* RISC-V GNU Toolchain
+* RISC-V OpenOCD (for use with development board and FPGA targets)
-```
-git submodule update --init --recursive
-```
-
-To see Makefile options:
-
-```
-cd freedom-e-sdk
-make help
-```
-
-#### Install the RISC-V Toolchain ####
+##### Install the RISC-V Toolchain and OpenOCD #####
The RISC-V GNU Toolchain and OpenOCD are available from the SiFive Website at
@@ -77,45 +155,83 @@ export RISCV_OPENOCD_PATH=/my/desired/location/openocd
export RISCV_PATH=/my/desired/location/riscv64-unknown-elf-gcc-<date>-<version>
```
+#### 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:
```
-cd freedom-e-sdk
git pull origin master
git submodule update --init --recursive
```
### Using the Tools ###
+To ease the transition for consumers of the Legacy SDK, we've namespaced
+the new Freedom Metal examples behind the environment variable `BSP`. To use the
+Freedom Metal examples, you may `export BSP=mee` in your shell environment, or simply
+pass `BSP=mee` as an argument to your `make` invocations as you see in the following
+example commands.
+
#### Building an Example ####
To compile a bare-metal RISC-V program:
```
-cd freedom-e-sdk
make BSP=mee [PROGRAM=hello] [BOARD=sifive-hifive1] 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 `sifive-hifive1` target.
+If, for example, you wished to build the `timer-interrupt` example for the S51
+Arty FPGA Evaluation target, you would instead run the command
+
+```
+make BSP=mee PROGRAM=timer-interrupt BOARD=coreip-s51-arty software
+```
+
+#### Building a Legacy Example ####
+
+The legacy examples can still be built by omitting `BSP=mee` or by substituting
+`BSP=legacy`. For example, to build the legacy `demo_gpio` application for
+HiFive 1, run:
+
+```
+make PROGRAM=demo_gpio BOARD=freedom-e300-hifive1 software
+```
+
#### Uploading to the Target Board ####
```
-cd freedom-e-sdk
make BSP=mee [PROGRAM=hello] [BOARD=sifive-hifive1] upload
```
#### Debugging a Target Program ####
```
-cd freedom-e-sdk
make BSP=mee [PROGRAM=hello] [BOARD=sifive-hifive1] debug
```
#### Cleaning a Target Program Build Directory ####
```
-cd freedom-e-sdk
make BSP=mee [PROGRAM=hello] [BOARD=sifive-hifive1] clean
```
@@ -123,6 +239,10 @@ Run `make help` for more commands.
### Benchmarking ###
+The Dhrystone and CoreMark benchmarks are still only supported by the Legacy
+Freedom E SDK. When we port the benchmarks to Freedom Metal, we will update
+this section to describe the updated build steps.
+
#### Dhrystone ####
After setting up the software and debug toolchains, you can build and