From 0df6996fcbd3cdfbb7614b4fcc7e83e41cea1f23 Mon Sep 17 00:00:00 2001 From: Nathaniel Graff Date: Tue, 29 Jan 2019 13:32:11 -0800 Subject: Init Sphinx docs for E SDK Signed-off-by: Nathaniel Graff --- doc/Makefile | 22 +++++ doc/README.md | 41 ++++++++ doc/sphinx/conf.py | 184 ++++++++++++++++++++++++++++++++++++ doc/sphinx/index.rst | 24 +++++ doc/sphinx/userguide.rst | 8 ++ doc/sphinx/userguide/installing.rst | 4 + 6 files changed, 283 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/README.md create mode 100644 doc/sphinx/conf.py create mode 100644 doc/sphinx/index.rst create mode 100644 doc/sphinx/userguide.rst create mode 100644 doc/sphinx/userguide/installing.rst diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..972a080 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,22 @@ +# Copyright (c) 2019 SiFive Inc. +# +# Documentation Build + +.PHONY: all +all: html + +########################### +# Build HTML Documentation +########################### + +.PHONY: html +html: html/index.html + +# Use Sphinx to build HTML from Doxygen XML +html/index.html: sphinx/* + sphinx-build -b html sphinx html + +.PHONY: clean +clean: + rm -rf html + diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..9fd78df --- /dev/null +++ b/doc/README.md @@ -0,0 +1,41 @@ +# Documentation Generation + +## Requirements + +You'll need the following software: +- [Sphinx](http://www.sphinx-doc.org/en/master/index.html) + +### Ubuntu + +You can install the required software on Ubuntu with the following: + +``` +sudo apt install python3-sphinx +``` + +The second line can be omitted if you don't intend to build the PDF. + +### MacOS + +You can install the required software on MacOS with the following: + +``` +brew install sphinx-doc +``` + +The second line can be omitted if you don't intend to build the PDF. + +## Building the Docs + +You can generate the HTML documentation with +``` +make +``` + +You can clean the build files and outputs with + +``` +make clean +``` + + diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100644 index 0000000..d41a8a8 --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,184 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Freedom E SDK' +copyright = '2019, SiFive Inc.' +author = 'SiFive Inc.' + +# The short X.Y version +version = os.popen("git describe").read().strip() +# The full version, including alpha/beta/rc tags +release = version + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['esdktemplates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['esdkstatic'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} +html_sidebars = { '**': ['about.html', 'navigation.html', 'relations.html', 'searchbox.html']} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'FreedomESDKdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'FreedomESDK.tex', 'Freedom E SDK Documentation', + 'SiFive Inc.', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'freedomesdk', 'Freedom E SDK Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'FreedomESDK', 'Freedom E SDK Documentation', + author, 'FreedomESDK', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'metal' : ('https://sifive.github.io/freedom-metal-docs', None) } diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst new file mode 100644 index 0000000..e680a68 --- /dev/null +++ b/doc/sphinx/index.rst @@ -0,0 +1,24 @@ +Freedom E SDK +============= + +This is the documentatino for the SiFive Freedom E SDK |version|. + +Freedom E SDK is generally available from the `Freedom E SDK Repository`_. + +.. _Freedom E SDK Repository: + https://github.com/sifive/freedom-e-sdk + +Table of Contents +----------------- + +.. toctree:: + :maxdepth: 2 + + userguide + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/sphinx/userguide.rst b/doc/sphinx/userguide.rst new file mode 100644 index 0000000..f0ad5db --- /dev/null +++ b/doc/sphinx/userguide.rst @@ -0,0 +1,8 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 1 + :glob: + + userguide/* diff --git a/doc/sphinx/userguide/installing.rst b/doc/sphinx/userguide/installing.rst new file mode 100644 index 0000000..8684923 --- /dev/null +++ b/doc/sphinx/userguide/installing.rst @@ -0,0 +1,4 @@ +Installing Freedom E SDK +======================== + +Foo -- cgit v1.2.3 From 90fd18da87f58feb0fc389a65caa95f308b4817a Mon Sep 17 00:00:00 2001 From: Nathaniel Graff Date: Fri, 1 Feb 2019 10:23:47 -0800 Subject: Copy the contents of the README into the User Guide Signed-off-by: Nathaniel Graff --- doc/sphinx/contents.rst | 109 ++++++++++++++++++++++++++++++ doc/sphinx/index.rst | 14 ++++ doc/sphinx/userguide.rst | 5 +- doc/sphinx/userguide/benchmarking.rst | 55 +++++++++++++++ doc/sphinx/userguide/buildingcoreip.rst | 29 ++++++++ doc/sphinx/userguide/buildingdevboard.rst | 43 ++++++++++++ doc/sphinx/userguide/installing.rst | 75 +++++++++++++++++++- doc/sphinx/userguide/standalone.rst | 14 ++++ 8 files changed, 342 insertions(+), 2 deletions(-) create mode 100644 doc/sphinx/contents.rst create mode 100644 doc/sphinx/userguide/benchmarking.rst create mode 100644 doc/sphinx/userguide/buildingcoreip.rst create mode 100644 doc/sphinx/userguide/buildingdevboard.rst create mode 100644 doc/sphinx/userguide/standalone.rst 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 `_ + + - sifive-hifive1 + +- `SiFive Freedom E310 Arty `_ + + - 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//``. 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 `_ +(`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. + +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 `_. + 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) + + + + 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 + ``_. +- 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 `_. + +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--.tar.gz /my/desired/location/ + cp riscv64-unknown-elf-gcc--.tar.gz /my/desired/location + cd /my/desired/location + tar -xvf openocd--.tar.gz + tar -xvf riscv64-unknown-elf-gcc--.tar.gz + export RISCV_OPENOCD_PATH=/my/desired/location/openocd + export RISCV_PATH=/my/desired/location/riscv64-unknown-elf-gcc-- + +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 + -- cgit v1.2.3 From c1e8371e61dd1b36473302438fdd49d936a72d87 Mon Sep 17 00:00:00 2001 From: Nathaniel Graff Date: Fri, 1 Feb 2019 10:55:46 -0800 Subject: Add link to github.io docs to README Signed-off-by: Nathaniel Graff --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 297412e..4ba9ee8 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ 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](https://sifive.github.io/freedom-e-sdk-docs/index.html) + ### Under Construction ### This repository is currently under construction as we transition from the -- cgit v1.2.3 From 8565ab59da981d542febae1e93281c09c447c50c Mon Sep 17 00:00:00 2001 From: Nathaniel Graff Date: Wed, 6 Feb 2019 11:13:12 -0800 Subject: Add published documentation as submodule Signed-off-by: Nathaniel Graff --- .gitmodules | 3 +++ doc/html | 1 + 2 files changed, 4 insertions(+) create mode 160000 doc/html diff --git a/.gitmodules b/.gitmodules index a304a8f..c06c4c2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -28,3 +28,6 @@ [submodule "software/example-pmp"] path = software/example-pmp url = https://github.com/sifive/example-pmp.git +[submodule "doc/html"] + path = doc/html + url = https://github.com/sifive/freedom-e-sdk-docs.git diff --git a/doc/html b/doc/html new file mode 160000 index 0000000..375bb50 --- /dev/null +++ b/doc/html @@ -0,0 +1 @@ +Subproject commit 375bb5043687b7eeb0fa91e4af4b5c937e1e70fd -- cgit v1.2.3