diff options
Diffstat (limited to 'doc/sphinx')
| -rw-r--r-- | doc/sphinx/contents.rst | 109 | ||||
| -rw-r--r-- | doc/sphinx/index.rst | 14 | ||||
| -rw-r--r-- | doc/sphinx/userguide.rst | 5 | ||||
| -rw-r--r-- | doc/sphinx/userguide/benchmarking.rst | 55 | ||||
| -rw-r--r-- | doc/sphinx/userguide/buildingcoreip.rst | 29 | ||||
| -rw-r--r-- | doc/sphinx/userguide/buildingdevboard.rst | 43 | ||||
| -rw-r--r-- | doc/sphinx/userguide/installing.rst | 75 | ||||
| -rw-r--r-- | doc/sphinx/userguide/standalone.rst | 14 |
8 files changed, 342 insertions, 2 deletions
diff --git a/doc/sphinx/contents.rst b/doc/sphinx/contents.rst new file mode 100644 index 0000000..b207a56 --- /dev/null +++ b/doc/sphinx/contents.rst @@ -0,0 +1,109 @@ +Contents of the SDK +=================== + +Supported Targets +----------------- + +Freedom E SDK comes packaged with the following board support packages under the +``bsp/`` directory. + +- `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. + +Freedom Metal +------------- + +`Freedom Metal <https://github.com/sifive/freedom-metal>`_ +(`Documentation <https://sifive.github.io/freedom-metal-docs/index.html>`_) +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. + +Freedom E SDK is a consumer of the Freedom Metal library. Freedom Metal allows the +SDK examples to be portable to all supported SiFive targets. + +Example Programs +---------------- + +The example programs can be found under the ``software/`` directory. + +- 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 + +- example-pmp + + - Demonstrates how to configure a Physical Memory Protection (PMP) region + diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index e680a68..a8f0809 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -8,12 +8,26 @@ Freedom E SDK is generally available from the `Freedom E SDK Repository`_. .. _Freedom E SDK Repository: https://github.com/sifive/freedom-e-sdk +What is Freedom E SDK? +---------------------- + +Freedom E SDK is a project maintained by Sifive Inc. which makes it easy to +get started developing software for the Freedom E and Freedom S Embedded +RISC-V Platforms. + +**UNDER CONSTRUCTION** + +Freedom E SDK is currently under construction as we transition from the +legacy Freedom E SDK API to the new +`Freedom Metal Compatibility Library <https://github.com/sifive/freedom-metal>`_. + Table of Contents ----------------- .. toctree:: :maxdepth: 2 + contents userguide diff --git a/doc/sphinx/userguide.rst b/doc/sphinx/userguide.rst index f0ad5db..c54e674 100644 --- a/doc/sphinx/userguide.rst +++ b/doc/sphinx/userguide.rst @@ -2,7 +2,10 @@ User Guide ========== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :glob: + userguide/installing + userguide/building* + userguide/standalone userguide/* 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 index 8684923..6e57425 100644 --- a/doc/sphinx/userguide/installing.rst +++ b/doc/sphinx/userguide/installing.rst @@ -1,4 +1,77 @@ Installing Freedom E SDK ======================== -Foo +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 + |