sifive · keith-packard · Sep 3, 2020 · Sep 8, 2020 · Sep 8, 2020 · Sep 24, 2020
diff --git a/Doxyfile b/Doxyfile
diff --git a/doc/Dockerfile b/doc/Dockerfile
@@ -0,0 +1,10 @@
+FROM sphinxdoc/sphinx
+
+RUN apt-get update \
+ && apt install -y doxygen graphviz \
+ && apt-get autoremove \
+ && apt-get clean
+
+RUN python3 -m pip install breathe pydot
+
+WORKDIR /
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,54 @@
+# Copyright (c) 2019 SiFive Inc.
+#
+# Documentation Build
+
+export RELEASE_TAG ?= unreleased
+
+.PHONY: all
+all: html pdf
+
+.PHONY: clean
+clean: clean-pdf clean-html clean-xml
+
+##########################
+# Build PDF Documentation
+##########################
+
+.PHONY: pdf
+pdf: latex/FreedomMetal.pdf
+
+latex/FreedomMetal.pdf: latex/FreedomMetal.tex
+	$(MAKE) -C latex
+
+latex/FreedomMetal.tex: xml/index.xml sphinx/*
+	sphinx-build -b latex sphinx latex
+
+.PHONY: clean-pdf
+clean-pdf:
+	rm -rf latex
+
+###########################
+# Build HTML Documentation
+###########################
+
+.PHONY: html
+html: html/index.html
+
+# Use Sphinx to build HTML from Doxygen XML
+html/index.html: xml/index.xml sphinx/*
+	sphinx-build -b html sphinx html
+
+.PHONY: clean-html
+clean-html:
+	rm -rf html/* html/.buildinfo html/.doctrees
+
+##########################
+# Build XML Documentation
+##########################
+
+xml/index.xml: ../metal/*.h
+	cd .. && doxygen
+
+.PHONY: clean-xml
+clean-xml:
+	rm -rf xml
diff --git a/doc/README.md b/doc/README.md
@@ -0,0 +1,55 @@
+# Documentation Generation
+
+## Requirements
+
+You'll need the following software:
+- [Doxygen](http://www.doxygen.nl/index.html)
+- [Sphinx](http://www.sphinx-doc.org/en/master/index.html)
+- LaTeX (For building a PDF)
+
+### Ubuntu
+
+You can install the required software on Ubuntu with the following:
+
+```
+sudo apt install doxygen python3-sphinx python3-breathe graphviz python3-pydot
+sudo apt install texlive-full latexmk
+```
+
+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 doxygen sphinx-doc graphviz
+brew cask install mactex
+```
+
+The second line can be omitted if you don't intend to build the PDF.
+
+## Building the Docs
+
+You can generate both the HTML and PDF documentation with
+```
+make
+```
+
+Or only the HTML or PDF docs using
+
+```
+make html
+```
+or
+
+```
+make pdf
+```
+
+You can clean the build files and outputs with
+
+```
+make clean
+```
+
diff --git a/doc/doc-old/.gitignore b/doc/doc-old/.gitignore
@@ -0,0 +1 @@
+xml/
diff --git a/doc/sphinx/api.rst b/doc/sphinx/api.rst
@@ -0,0 +1,17 @@
+.. _api-reference-label:
+
+*************
+API Reference
+*************
+
+.. _apireference:
+
+The API documentation aims to provide a complete reference to the
+Freedom Metal API. The API documentation is split into sections
+corresponding to each feature.
+
+.. toctree::
+   :glob:
+
+   apiref/*
+
diff --git a/doc/sphinx/apiref/atomic.rst b/doc/sphinx/apiref/atomic.rst
@@ -0,0 +1,6 @@
+Atomics
+=======
+
+.. doxygenfile:: metal/atomic.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/button.rst b/doc/sphinx/apiref/button.rst
@@ -0,0 +1,6 @@
+Buttons
+=======
+
+.. doxygenfile:: metal/button.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/cache.rst b/doc/sphinx/apiref/cache.rst
@@ -0,0 +1,6 @@
+Caches
+======
+
+.. doxygenfile:: metal/cache.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/clock.rst b/doc/sphinx/apiref/clock.rst
@@ -0,0 +1,26 @@
+Clocks
+======
+
+.. doxygenfile:: metal/clock.h
+   :project: metal
+
+Abstract Clock Devices
+----------------------
+
+.. doxygenfile:: metal/drivers/fixed_clock.h
+   :project: metal
+
+.. doxygenfile:: metal/drivers/fixed_factor_clock.h
+   :project: metal
+
+SiFive Clock Devices
+--------------------
+
+.. doxygenfile:: metal/drivers/sifive_fe310_g000_hfrosc.h
+   :project: metal
+
+.. doxygenfile:: metal/drivers/sifive_fe310_g000_hfxosc.h
+   :project: metal
+
+.. doxygenfile:: metal/drivers/sifive_fe310_g000_lfrosc.h
+   :project:metal
diff --git a/doc/sphinx/apiref/cpu.rst b/doc/sphinx/apiref/cpu.rst
@@ -0,0 +1,6 @@
+CPU
+===
+
+.. doxygenfile:: metal/cpu.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/csr.rst b/doc/sphinx/apiref/csr.rst
@@ -0,0 +1,6 @@
+CSR
+===
+
+.. doxygenfile:: metal/csr.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/exception.rst b/doc/sphinx/apiref/exception.rst
@@ -0,0 +1,5 @@
+Exception Handlers
+==================
+
+.. doxygenfile:: metal/exception.h
+   :project: metal
diff --git a/doc/sphinx/apiref/gpio.rst b/doc/sphinx/apiref/gpio.rst
@@ -0,0 +1,5 @@
+GPIO
+====
+
+.. doxygenfile:: metal/gpio.h
+   :project: metal
diff --git a/doc/sphinx/apiref/hpm.rst b/doc/sphinx/apiref/hpm.rst
@@ -0,0 +1,6 @@
+Hardware Performance Monitors
+=============================
+
+.. doxygenfile:: metal/hpm.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/i2c.rst b/doc/sphinx/apiref/i2c.rst
@@ -0,0 +1,6 @@
+I2C
+===
+
+.. doxygenfile:: metal/i2c.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/init.rst b/doc/sphinx/apiref/init.rst
@@ -0,0 +1,7 @@
+Constructors
+============
+
+.. doxygenfile:: metal/init.h
+   :project: metal
+   :no-link:
+
diff --git a/doc/sphinx/apiref/interrupt.rst b/doc/sphinx/apiref/interrupt.rst
@@ -0,0 +1,11 @@
+Interrupts
+==========
+
+.. doxygenfile:: metal/interrupt.h
+   :project: metal
+
+.. doxygenfile:: metal/drivers/riscv_cpu_intc.h
+   :project: metal
+
+.. doxygenfile:: metal/drivers/riscv_plic0.h
+   :project: metal
diff --git a/doc/sphinx/apiref/io.rst b/doc/sphinx/apiref/io.rst
@@ -0,0 +1,5 @@
+Input/Output declarations
+=========================
+
+.. doxygenfile:: metal/io.h
+   :project: metal
diff --git a/doc/sphinx/apiref/itim.rst b/doc/sphinx/apiref/itim.rst
@@ -0,0 +1,7 @@
+ITIM
+====
+
+.. doxygenfile:: metal/itim.h
+   :project: metal
+   :no-link:
+
diff --git a/doc/sphinx/apiref/led.rst b/doc/sphinx/apiref/led.rst
@@ -0,0 +1,6 @@
+LEDs
+====
+
+.. doxygenfile:: metal/led.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/lock.rst b/doc/sphinx/apiref/lock.rst
@@ -0,0 +1,6 @@
+Locks
+=======
+
+.. doxygenfile:: metal/lock.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/pmp.rst b/doc/sphinx/apiref/pmp.rst
@@ -0,0 +1,6 @@
+PMPs
+====
+
+.. doxygenfile:: metal/pmp.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/privilege.rst b/doc/sphinx/apiref/privilege.rst
@@ -0,0 +1,5 @@
+Privilege Modes
+===============
+
+.. doxygenfile:: metal/privilege.h
+   :project: metal
diff --git a/doc/sphinx/apiref/pwm.rst b/doc/sphinx/apiref/pwm.rst
@@ -0,0 +1,6 @@
+PWM
+===
+
+.. doxygenfile:: metal/pwm.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/riscv.rst b/doc/sphinx/apiref/riscv.rst
@@ -0,0 +1,5 @@
+RISC-V Processor Definitions
+============================
+
+.. doxygenfile:: metal/riscv.h
+   :project: metal
diff --git a/doc/sphinx/apiref/rtc.rst b/doc/sphinx/apiref/rtc.rst
@@ -0,0 +1,6 @@
+Real-Time Clock
+===============
+
+.. doxygenfile:: metal/rtc.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/shutdown.rst b/doc/sphinx/apiref/shutdown.rst
@@ -0,0 +1,6 @@
+Shutdown
+========
+
+.. doxygenfile:: metal/shutdown.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/spi.rst b/doc/sphinx/apiref/spi.rst
@@ -0,0 +1,6 @@
+SPI
+===
+
+.. doxygenfile:: metal/spi.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/switch.rst b/doc/sphinx/apiref/switch.rst
@@ -0,0 +1,6 @@
+Switches
+========
+
+.. doxygenfile:: metal/switch.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/time.rst b/doc/sphinx/apiref/time.rst
@@ -0,0 +1,6 @@
+Time
+====
+
+.. doxygenfile:: metal/time.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/timer.rst b/doc/sphinx/apiref/timer.rst
@@ -0,0 +1,6 @@
+Timer API
+=========
+
+.. doxygenfile:: metal/timer.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/tty.rst b/doc/sphinx/apiref/tty.rst
@@ -0,0 +1,6 @@
+TTY
+===
+
+.. doxygenfile:: metal/tty.h
+   :project: metal
+
diff --git a/doc/sphinx/apiref/uart.rst b/doc/sphinx/apiref/uart.rst
@@ -0,0 +1,5 @@
+UART
+====
+
+.. doxygenfile:: metal/uart.h
+   :project: metal
diff --git a/doc/sphinx/apiref/watchdog.rst b/doc/sphinx/apiref/watchdog.rst
@@ -0,0 +1,6 @@
+Watchdog
+========
+
+.. doxygenfile:: metal/watchdog.h
+   :project: metal
+