Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Next docs #337

Open
wants to merge 3 commits into
base: freedom-metal-next
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,537 changes: 2,537 additions & 0 deletions Doxyfile

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions doc/Dockerfile
Original file line number Diff line number Diff line change
@@ -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 /
54 changes: 54 additions & 0 deletions doc/Makefile
Original file line number Diff line number Diff line change
@@ -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
55 changes: 55 additions & 0 deletions doc/README.md
Original file line number Diff line number Diff line change
@@ -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
```

1 change: 1 addition & 0 deletions doc/doc-old/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
xml/
170 changes: 170 additions & 0 deletions doc/mee-spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# MEE Specification

The MEE is designed to provide a source-level compatibility for
bare-metal code between platforms. This specification defines the
publicly available API. The intent is that this API is stable so users
can rely on it not changing, but we're not going to make any guarantees
about it until our 1.0.0 release.

Note that the MEE does not define an ABI -- specifically that means that
binaries will not be compatible between different versions of the MBI,
or between different platforms.

## User API

The core of the MEE is a C API that is designed to allow programmers to
write portable bare-metal embedded code.

Any symbol beginning with `__mee_` is internal to the MEE and must not
be called or defined by user code. Symbols beginning with `mee_` are
public interfaces and can be considered to be a stable API. The best
documentation for most of these symbols are found in the code, but some
is listed below.

### Clock Interface

The clock interface allows for controlling the rate of various clocks in
the system. Clocks are defined by a pointer to a `struct mee_clock`, the
contents of which is implementation defined. Users of the clock
interface must call the functions defined below in order to interact
with a `struct mee_clock *`.

Note that no mechanism for obtaining a pointer to a `struct mee_clock`
has been defined, making it impossible to call any of these functions
without invoking implementation-defined behavior.

#### `long mee_clock_get_rate_hz(const struct mee_clock *clock)`

Returns the clock rate of the given clock, in Hz.

#### `long mee_clock_set_rate_hz(const struct mee_clock *clock, long hz)`

Attempts to set the rate of the given clock to the given value, in Hz.
Returns the rate the given clock was actually set to, which may be
different than the requested rate. There are no hard requirements on
what clock rates can be set, but it's expected that a best effort
approach is taken to match the caller's desired clock rate.

#### `void mee_clock_register_rate_change_callback(struct mee_clock *clk, int (*cb)(struct mee_clock *, void *), void *priv)`

Registers a function (and an associated opaque data block) that will be
called whenever the giver clock's rate has been changed. This function
will be called after the driver-specific clock frequency changing code
has returned, but before the caller of `mee_clock_set_rate_hz()` has
been returned to.

It's not guaranteed that the given clock's rate will have actually
changed every time the given function is called, but it's guaranteed
that the given function will be called every time the given clock's rate
has been changed.

### Timer Interface

The timer interface allows for access of various timers values in
the system. Timers are defined by a pointer to a `struct mee_timer`, the
contents of which is implementation defined. Users of the timer
interface must call the functions defined below in order to interact
with a `struct mee_timer *`.

Note that no mechanism for obtaining a pointer to a `struct mee_timer`
has been defined, making it impossible to call any of these functions
without invoking implementation-defined behavior.

#### `int mee_timer_get_cyclecount(int hartid, unsigned long long *mcc)`

Returns the cpu machine cycle count of a given hartid.

#### `int mee_timer_get_timebase_frequency(int hartid, unsigned long long *timebase)`

Returns the timebase frequency of a given hartid, s.t a time elapse duration can determined.
For example, a timebase frequency of 1000000 (1MHz) will have each cycle count of 1s.

#### `void mee_timer_init(const struct mee_timer *timer, unsigned long long timebase)`

Setup the timebase frequency for a given timer, in Hz.

### Power Control Interface

The MEE defines a mechanism to control the power state of a given
machine. The interface is currently quite simple: it's just the
`mee_shutdown()` function.

#### `void mee_shutdown(int code) __attribute__((noreturn))`

Terminates execution of this program, attempting to pass the given code
to whomever may be looking. The code `0` indicates success, while all
other codes indicate failure. The exact mechanism by which execution
terminates is implementation defined, but some examples include:

* Spinning in an infinite loop.
* Printing the return code to standard out and spinning in an infinite
loop.
* Toggling an external I/O to disable the power to the core.
* Poking through a hole to the host that's providing this environment
and indicating success or failure.

### TTY Interface

The MEE provides an terminal interface. This interface is designed to
provide a simple mechanism for getting text-based data outside of the
MEE -- in other words, it's designed to be used to implement C library
functions like `printf()`.

#### `int mee_tty_putc(unsigned char c);`

Writes the given character to the default terminal, returning 0 on
success or -1 on failure.

### UART Interface

The UART interface allows users of the MEE to control

Note that there is no mechanism for obtaining a pointer to a `struct
mee_uart` without invoking implementation-defined behavior, thus making
calling any of these functions impossible.

#### `int mee_uart_init(struct mee_uart *uart)`

Initializes the given UART. This must be called exactly once before any
other function on this UART can be called. It is invalid to initialize
a UART more than once.

#### `int mee_uart_putc(struct mee_uart *uart, unsigned char c)`

Writes the given character to the given UART, returning 0 on success and
-1 on failure.

#### `int mee_uart_getc(struct mee_uart *uart, unsigned char *c)`

Reads a character from the given UART, storing it at the given character
pointer. This returns 0 on success and -1 on failure.

#### `int mee_uart_get_baud_rate(struct mee_uart *uart)`

Obtains the baud rate of the given UART, or `-1` to signify an error.

#### `int mee_uart_set_baud_rate(struct mee_uart *uart, int baud_rate)`

Sets the baud rate of the given UART. Returns 0 on success, or -1 on
failure. Failure to set the baud rate can render the UART unusable
until a subsequent coll to `mee_uart_set_baud_rate()` returns success.

### C Startup Interface

The MEE handles entering the C library's start routine, which is defined
by the symbol `_start`. This symbol must be defined by the C library in
order to allow the MEE to do anything meaningful.

The MEE follows the standard RISC-V bootloader ABI when calling
`_start`:

* `a0` contains the hart ID.
* `a1` contains a pointer to the machine description. The MEE always
sets this to NULL, as machines are described statically.
* `a2` contains a callback that should be called from within the child
environment after it has initialized itself.

This can be described as a the C function `void _start(long hartid,
unsigned char *dtb, void (*after_init)(void))'. Note that the MEE does
not initialize a C environment and therefor this cannot actually be a C
function -- for example, there may not be a stack.
13 changes: 13 additions & 0 deletions doc/sphinx/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
API Reference
=============

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/*

6 changes: 6 additions & 0 deletions doc/sphinx/apiref/atomic.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Atomics
=======

.. doxygenfile:: metal/atomic.h
:project: metal

6 changes: 6 additions & 0 deletions doc/sphinx/apiref/button.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Buttons
=======

.. doxygenfile:: metal/button.h
:project: metal

6 changes: 6 additions & 0 deletions doc/sphinx/apiref/cache.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Caches
======

.. doxygenfile:: metal/cache.h
:project: metal

26 changes: 26 additions & 0 deletions doc/sphinx/apiref/clock.rst
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions doc/sphinx/apiref/cpu.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
CPU
===

.. doxygenfile:: metal/cpu.h
:project: metal

6 changes: 6 additions & 0 deletions doc/sphinx/apiref/csr.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
CSR
===

.. doxygenfile:: metal/csr.h
:project: metal

5 changes: 5 additions & 0 deletions doc/sphinx/apiref/exception.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Exception Handlers
==================

.. doxygenfile:: metal/exception.h
:project: metal
5 changes: 5 additions & 0 deletions doc/sphinx/apiref/gpio.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
GPIO
====

.. doxygenfile:: metal/gpio.h
:project: metal
6 changes: 6 additions & 0 deletions doc/sphinx/apiref/hpm.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Hardware Performance Monitors
=============================

.. doxygenfile:: metal/hpm.h
:project: metal

6 changes: 6 additions & 0 deletions doc/sphinx/apiref/i2c.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
I2C
===

.. doxygenfile:: metal/i2c.h
:project: metal

Loading