Merge pull request #169 from sifive/documentation

Add initial documentation

12 files changed, 623 insertions, 0 deletions

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/html b/doc/html
new file mode 160000
+Subproject 375bb5043687b7eeb0fa91e4af4b5c937e1e70f
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/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
new file mode 100644
index 0000000..a8f0809
--- /dev/null
+++ b/doc/sphinx/index.rst
@@ -0,0 +1,38 @@
+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
+
+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
+
+
+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..c54e674
--- /dev/null
+++ b/doc/sphinx/userguide.rst
@@ -0,0 +1,11 @@
+User Guide
+==========
+
+.. toctree::
+   :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
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
+