summaryrefslogtreecommitdiff
path: root/doc/sphinx/userguide
diff options
context:
space:
mode:
authorNathaniel Graff <nathaniel.graff@sifive.com>2019-02-06 19:15:22 +0000
committerGitHub <noreply@github.com>2019-02-06 19:15:22 +0000
commit30837cf2279ec60989898a0d8ef5a1934bd443c0 (patch)
tree40b70bb9de7ec17e6ce5e8b876eaad0a07a210e1 /doc/sphinx/userguide
parent4c20f5158e506f3c13cf66d5259a6399a6b4b2a3 (diff)
parent8565ab59da981d542febae1e93281c09c447c50c (diff)
Merge pull request #169 from sifive/documentation
Add initial documentation
Diffstat (limited to 'doc/sphinx/userguide')
-rw-r--r--doc/sphinx/userguide/benchmarking.rst55
-rw-r--r--doc/sphinx/userguide/buildingcoreip.rst29
-rw-r--r--doc/sphinx/userguide/buildingdevboard.rst43
-rw-r--r--doc/sphinx/userguide/installing.rst77
-rw-r--r--doc/sphinx/userguide/standalone.rst14
5 files changed, 218 insertions, 0 deletions
diff --git a/doc/sphinx/userguide/benchmarking.rst b/doc/sphinx/userguide/benchmarking.rst
new file mode 100644
index 0000000..b308adb
--- /dev/null
+++ b/doc/sphinx/userguide/benchmarking.rst
@@ -0,0 +1,55 @@
+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
+execute everyone's favorite benchmark as follows:
+
+- Compile the benchmark with the command ``make software TARGET=freedom-e300-hifive1 PROGRAM=dhrystone LINK_TARGET=dhrystone``. Note that a slightly different linker file is used for Dhrystone which stores read only data in DTIM instead of external flash.
+- Run on the HiFive1 board with the command ``make upload TARGET=freedom-e300-hifive1 PROGRAM=dhrystone``.
+ This will take a few minutes. Sample output is provided below.
+- Compute DMIPS by dividing the Dhrystones per Second result by 1757, which
+ was the VAX 11/780's performance. In the example below, 729927 / 1757 =
+ 415 DMIPS.
+- Compute DMIPS/MHz by dividing by the clock rate: in the example below,
+ 415 / 268 = 1.55 DMIPS/MHz.
+
+.. code-block:: none
+
+ core freq at 268694323 Hz
+
+ Dhrystone Benchmark, Version 2.1 (Language: C)
+
+ <snip>
+
+ Microseconds for one run through Dhrystone: 1.3
+ Dhrystones per Second: 729927.0
+
+CoreMark
+--------
+
+We cannot distribute the CoreMark benchmark, but following are instructions
+to download and run the benchmark on the HiFive1 board:
+
+- Download CoreMark from EEMBC's web site and extract the archive from
+ `<http://www.eembc.org/coremark/download.php>`_.
+- Copy the following files from the extracted archive into the
+ ``software/coremark`` directory in this repository:
+
+ - ``core_list_join.c``
+ - ``core_main.c``
+ - ``coremark.h``
+ - ``core_matrix.c``
+ - ``core_state.c``
+ - ``core_util.c``
+
+- Compile the benchmark with the command ``make software PROGRAM=coremark``.
+- Run on the HiFive1 board with the command ``make upload PROGRAM=coremark``.
+- Divide the reported Iterations/Sec by the reported core frequency in MHz to
+ obtain a CoreMarks/MHz value.
diff --git a/doc/sphinx/userguide/buildingcoreip.rst b/doc/sphinx/userguide/buildingcoreip.rst
new file mode 100644
index 0000000..a6f1dae
--- /dev/null
+++ b/doc/sphinx/userguide/buildingcoreip.rst
@@ -0,0 +1,29 @@
+Building for SiFive CoreIP
+==========================
+
+Building an Example
+-------------------
+
+To compile a bare-metal RISC-V program:
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=coreip-e31] 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 ``coreip-e31`` target.
+If, for example, you wished to build the ``timer-interrupt`` example for the S51
+Core IP target, you would instead run the command
+
+.. code-block:: bash
+
+ make BSP=mee PROGRAM=timer-interrupt TARGET=coreip-s51 software
+
+Cleaning a Target Program Build Directory
+-----------------------------------------
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=coreip-e31] clean
+
diff --git a/doc/sphinx/userguide/buildingdevboard.rst b/doc/sphinx/userguide/buildingdevboard.rst
new file mode 100644
index 0000000..4b5822b
--- /dev/null
+++ b/doc/sphinx/userguide/buildingdevboard.rst
@@ -0,0 +1,43 @@
+Building for a Dev Board or FPGA
+================================
+
+Building an Example
+-------------------
+
+To compile a bare-metal RISC-V program:
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=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
+
+.. code-block:: bash
+
+ make BSP=mee PROGRAM=timer-interrupt TARGET=coreip-s51-arty software
+
+Uploading to the Target Board
+-----------------------------
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=sifive-hifive1] upload
+
+Debugging a Target Program
+--------------------------
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=sifive-hifive1] debug
+
+Cleaning a Target Program Build Directory
+-----------------------------------------
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=sifive-hifive1] clean
+
diff --git a/doc/sphinx/userguide/installing.rst b/doc/sphinx/userguide/installing.rst
new file mode 100644
index 0000000..6e57425
--- /dev/null
+++ b/doc/sphinx/userguide/installing.rst
@@ -0,0 +1,77 @@
+Installing Freedom E SDK
+========================
+
+Supported Systems
+-----------------
+
+Freedom E SDK is supported on Linux, MacOS, and Windows.
+
+Linux support is officially provided to distributions we distribute
+builds of the RISC-V toolchain for. Currently, these distributions are
+
+- Ubuntu
+- CentOS
+
+We expect other Linux distributions to work as well, provided that the
+user can either run our provided toolchains on them or produce their own
+toolchain.
+
+Windows support is not directly provided by Freedom E SDK, but through
+our Integrated Development Environment, Freedom Studio.
+
+Prerequisites
+-------------
+
+To use this SDK, you will need the following software available on your machine:
+
+- GNU Make
+- Git
+- The RISC-V GNU Embedded Toolchain
+- RISC-V OpenOCD (for use with development board and FPGA targets)
+
+Install the RISC-V Toolchain and OpenOCD
+----------------------------------------
+
+The RISC-V GNU Toolchain and OpenOCD are available from `the SiFive Website <https://www.sifive.com/boards>`_.
+
+For OpenOCD and/or RISC-V GNU Toolchain, download the .tar.gz for your platform,
+and unpack it to your desired location. Then, set the ``RISCV_PATH`` and
+``RISCV_OPENOCD_PATH`` environment variables when using the tools:
+
+.. code-block:: bash
+
+ 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>
+
+Cloning the Repository
+----------------------
+
+This repository can be cloned by running the following commands:
+
+.. code-block:: bash
+
+ 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:
+
+.. code-block:: bash
+
+ git submodule update --init --recursive
+
+Updating the SDK
+----------------
+
+If you'd like to update your SDK to the latest version:
+
+.. code-block:: bash
+
+ git pull origin master
+ git submodule update --init --recursive
diff --git a/doc/sphinx/userguide/standalone.rst b/doc/sphinx/userguide/standalone.rst
new file mode 100644
index 0000000..58f7f51
--- /dev/null
+++ b/doc/sphinx/userguide/standalone.rst
@@ -0,0 +1,14 @@
+Creating 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.
+
+.. code-block:: bash
+
+ make BSP=mee [PROGRAM=hello] [TARGET=sifive-hifive1] STANDALONE_DEST=/path/to/desired/location standalone
+