403 lines
16 KiB
HTML
403 lines
16 KiB
HTML
<!doctype html>
|
|
<html>
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<title>Paying It Forward: Documenting your Hardware</title>
|
|
|
|
<meta name="description" content="A framework for easily creating beautiful presentations using HTML">
|
|
<meta name="author" content="Sean "xobs" Cross">
|
|
|
|
<meta name="apple-mobile-web-app-capable" content="yes">
|
|
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
|
|
|
<link rel="stylesheet" href="css/reveal.css">
|
|
<link rel="stylesheet" href="css/theme/lca2020.css" id="theme">
|
|
|
|
<!-- Theme used for syntax highlighting of code -->
|
|
<link rel="stylesheet" href="lib/css/zenburn.css">
|
|
|
|
<!-- Printing and PDF exports -->
|
|
<script>
|
|
var link = document.createElement('link');
|
|
link.rel = 'stylesheet';
|
|
link.type = 'text/css';
|
|
link.href = window.location.search.match(/print-pdf/gi) ? 'css/print/pdf.css' : 'css/print/paper.css';
|
|
document.getElementsByTagName('head')[0].appendChild(link);
|
|
</script>
|
|
|
|
<!--[if lt IE 9]>
|
|
<script src="lib/js/html5shiv.js"></script>
|
|
<![endif]-->
|
|
|
|
<style>
|
|
/*********************************************
|
|
* ZOOM REVERSE TRANSITION (i.e. zoom out)
|
|
*********************************************/
|
|
.reveal .slides section[data-transition=zoomrev],
|
|
.reveal.zoomrev .slides section:not([data-transition]) {
|
|
transition-timing-function: ease;
|
|
}
|
|
|
|
.reveal .slides > section[data-transition=zoomrev].past,
|
|
.reveal .slides > section[data-transition~=zoomrev-out].past,
|
|
.reveal.zoomrev .slides > section:not([data-transition]).past {
|
|
visibility: hidden;
|
|
-webkit-transform: scale(0.2);
|
|
transform: scale(0.2);
|
|
}
|
|
|
|
.reveal .slides > section[data-transition=zoomrev].future,
|
|
.reveal .slides > section[data-transition~=zoomrev-in].future,
|
|
.reveal.zoomrev .slides > section:not([data-transition]).future {
|
|
visibility: hidden;
|
|
-webkit-transform: scale(16);
|
|
transform: scale(16);
|
|
}
|
|
|
|
.reveal .slides > section > section[data-transition=zoomrev].past,
|
|
.reveal .slides > section > section[data-transition~=zoomrev-out].past,
|
|
.reveal.zoomrev .slides > section > section:not([data-transition]).past {
|
|
-webkit-transform: translate(0, 150%);
|
|
transform: translate(0, 150%);
|
|
}
|
|
|
|
.reveal .slides > section > section[data-transition=zoomrev].future,
|
|
.reveal .slides > section > section[data-transition~=zoomrev-in].future,
|
|
.reveal.zoomrev .slides > section > section:not([data-transition]).future {
|
|
-webkit-transform: translate(0, -150%);
|
|
transform: translate(0, -150%);
|
|
}
|
|
</style>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- Start of main presentation -->
|
|
<div class="reveal">
|
|
<div class="footer">
|
|
<a class="url" href="https://p.xobs.io/lca20-pif/">p.xobs.io/lca20-pif</a>
|
|
<span class="theme">The Linux of Things</span><span class="hashtag"> | #LCA2020</span><span class="twitter"> |
|
|
@linuxconfau</span>
|
|
</div>
|
|
<div class="slides">
|
|
<section data-background-image="css/theme/lca2019-title-bg-transparent.svg">
|
|
<h1>Paying it Forward: Documenting Your Hardware Project</h1>
|
|
<h4>Approaches to documenting a hardware description language using lxsocdoc</h4>
|
|
<p align="right">
|
|
<small>Sean Cross - <a href="https://xobs.io/">https://xobs.io/</a> - @xobs</small>
|
|
</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Introduction</h2>
|
|
<aside class="notes">
|
|
This is the Open ISA miniconf, which today tends to mean FPGAs. This means that
|
|
hardware and software are both extensible, and developers will be able to extend
|
|
the hardware in addition to making modifications to your software package.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>About Me</h2>
|
|
<aside class="notes">
|
|
My name is Sean Cross, also known as "xobs". I will be speaking later this week
|
|
on the Betrusted project, but many know me as the main developer behind the Fomu
|
|
project. Fomu is an FPGA that fits in your USB port. One of my goals with the
|
|
Fomu project was to allow people to treat it as just a RISC-V CPU in their USB
|
|
port, which means now we need to make documentation. This talk covers some of
|
|
the problems I ran into while working on this project, and the solutions I came
|
|
up with.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Undocumented Hardware = Bad</h2>
|
|
<h4>(But so easy to do!)</h4>
|
|
<aside class="notes">
|
|
Undocumented hardware is bad. There are all sorts of quirks, and even if you have
|
|
the source code, it can be very difficult to read. I'm the primary developer for
|
|
the Fomu project, and this talk will cover some of the issues I've run into with
|
|
respect to documentation. It is most directly related to the LiteX and Migen
|
|
projects, but the concepts will carry over into any other Hardware Description
|
|
Language you may use.
|
|
|
|
The goal of this talk is to show how it's easy to document hardware with
|
|
the right framework, and how it's easier to have a project that's documented
|
|
than one that isn't.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Talk Outline</h2>
|
|
<aside class="notes">
|
|
I'll briefly cover various methods of writing HDL code, then cover the rationale
|
|
behind the approach we take with lxsocdoc, then give an example of how to use
|
|
lxsocdoc and how you might apply it to your language. Finally, I'll cover the
|
|
implications of having documented hardware and how this will help you pay it forward.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Motivation</h2>
|
|
<aside class="notes">
|
|
Verilog and VHDL are kind of the C or assembly of the FPGA world. They're universal,
|
|
but somewhat unwieldy to use. You need to manually set up your address decoders,
|
|
and documentation is very free-form. Common approaches today involve comments in
|
|
the HDL and/or C header files. This works, but we can do better. We just need to
|
|
describe the hardware better.
|
|
```//Hardware definitions of the SoC. Also is the main repo of documentation for the
|
|
//programmer-centric view of the hardware.```
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>About LiteX and lxsocdoc</h2>
|
|
<aside class="notes">
|
|
Fomu uses LiteX, which is related to Migen. This is a hardware description language
|
|
written in Python. You write Python code and run the program, and it generates
|
|
a design file -- either Verilog code, or a Yosys netlist. There are many other
|
|
alternatives such as SpinalHDL or Chisel. By writing in Python as opposed to
|
|
direct Verilog, we get a lot of nice primitives. The examples from this talk
|
|
are taken from lxsocdoc and LiteX, but most higher-level hardware description
|
|
languages can take similar approaches to documentation.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>LiteX Primitives</h2>
|
|
<aside class="notes">
|
|
In LiteX, two of the primitives used to expose hardware registers to the CPU softcore
|
|
are CSRStorage and CSRStatus. Instead of manually wiring up a crossbar and decoding
|
|
the addresses ourselves, we just need to write `self.regname = CSRStatus(8)`,
|
|
and the build system will wire up 8 bits of read-only memory to the target CPU.
|
|
Similarly, `self.othername = CSRStorage(8)` will give 8-bits of write-only memory.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h4>SPI Bitbang Module</h4>
|
|
<pre><code class="python" data-trim>self.bitbang = CSRStorage(4)
|
|
If(self.bitbang.storage[3],
|
|
dq.oe.eq(0)
|
|
).Else(
|
|
dq.oe.eq(1)
|
|
),
|
|
# CPOL=0/CPHA=0 or CPOL=1/CPHA=1 only.
|
|
If(self.bitbang.storage[1],
|
|
self.miso.status.eq(dq.i[1])
|
|
),
|
|
dq.o.eq(
|
|
Cat(self.bitbang.storage[0], Replicate(1, spi_width-1))
|
|
)</code></pre>
|
|
<aside class="notes">
|
|
This works well, but exposes a new problem: Documentation. As an example, I was
|
|
working with the SPI Flash block in litex, and wanted to know how the bitbang
|
|
driver worked. There wasn't any documentation except the source, which looked
|
|
like this.
|
|
|
|
You can kind of understand it, but it does take a lot of mental power to
|
|
work through it. I started by creating aliases for the various elements
|
|
in the storage array, but then I thought: There has to be a better way!
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Aside: Python Docstrings</h2>
|
|
<aside class="notes">
|
|
As an aside, Python has something called Pydoc and Docstrings. These are
|
|
comments that go at the top of functions and classes that let you describe
|
|
what a Python object is and how to use it. This is almost what we want,
|
|
except once the final SoC is generated we don't really care so much about
|
|
things like constructor arguments or method properties. Documentation for
|
|
the end user is different from documentation for the module developer.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h4>New Register Definition</h4>
|
|
<pre><code class="python" data-trim>self.bitbang = CSRStorage(4, fields=[
|
|
CSRField("mosi", description="Output value for MOSI pin, valid whenever ``dir`` is ``0``."),
|
|
CSRField("clk", description="Output value for SPI CLK pin."),
|
|
CSRField("cs_n", description="Output value for SPI CSn pin."),
|
|
CSRField("dir", description="Sets the direction for *ALL* SPI data pins except CLK and CSn.", values=[
|
|
("0", "OUT", "SPI pins are all output"),
|
|
("1", "IN", "SPI pins are all input"),
|
|
])
|
|
], description="""
|
|
Bitbang controls for SPI output. Only standard 1x SPI is supported, and as
|
|
a result all four wires are ganged together. This means that it is only possible
|
|
to perform half-duplex operations, using this SPI core.
|
|
""")</code></pre>
|
|
<aside class="notes">
|
|
This is when I hit upon the idea of `lxsocdoc`. The basic idea is that
|
|
Python is really good at introspecting Python, so let's add a little bit
|
|
more information to the CSR objects to make our life easier. And so, after
|
|
working with the LiteX creator Florent, we refactored the bitbang
|
|
definition to this.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h4>Refactored SPI Bitbang</h4>
|
|
<pre><code class="python" data-trim>If(self.bitbang.fields.dir,
|
|
dq.oe.eq(0)
|
|
).Else(
|
|
dq.oe.eq(1)
|
|
),
|
|
# CPOL=0/CPHA=0 or CPOL=1/CPHA=1 only.
|
|
If(self.bitbang.fields.clk,
|
|
self.miso.status.eq(dq.i[1])
|
|
),
|
|
dq.o.eq(
|
|
Cat(self.bitbang.fields.mosi, Replicate(1, spi_width-1))
|
|
)</code></pre>
|
|
<aside class="notes">
|
|
Now the actual bitbang logic looks like this.
|
|
|
|
This is a little bit easier to understand -- no longer are we looking at indices
|
|
in an array to determine what field does what. Instead we get actual named fields.
|
|
But because Python can introspect Python very easily, this is just the beginning.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Generating a Manual</h2>
|
|
<aside class="notes">
|
|
After the design is elaborated and the output file is generated, we can iterate
|
|
through the resulting tree and pick out any CSR objects and using any additional
|
|
information. We can actually generate a full reference manual, just like one you
|
|
would receive from a SoC Vendor.
|
|
|
|
For example, this is what the start of the Fomu SPI Flash documentation looks like:
|
|
[Register Listing for LXSPI]
|
|
|
|
This is already pretty useful. You can hand this file to someone and show them
|
|
how your design works. But the title of this talk is called "Paying it Forward",
|
|
and I can tell you from experience that having such a reference manual for yourself
|
|
while developing software for your own hardware is still invaluable. Hardware
|
|
designs are complex things, and not having to decode bitfield offsets in your
|
|
head or constantly referring to various sections of code to see how it's implemented
|
|
saves valuable time.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>More Documentation: ModuleDoc</h2>
|
|
<aside class="notes">
|
|
So now we have register documentation. Can we do better? Of course we can.
|
|
SoC reference manuals are more than just register definitions. They also include
|
|
background information on protocols, as well as more elaboration on how the block
|
|
works. We can take a cue from CSRs themselves, and add module documentation
|
|
in a similar fashion.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Protocol Documentation</h2>
|
|
<aside class="notes">
|
|
We can add additional documentation such as protocol waveforms. Here
|
|
we use WaveDrom to define the protocol of Wishbone-over-SPI. There
|
|
are multiple formats of the protocol depending on which version is
|
|
instantiated.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>SVD: Documentation for Machines</h2>
|
|
<aside class="notes">
|
|
Having documentation for humans is great, but we can go one step further and
|
|
make documentation for computers. SVD is an XML format defined by ARM that
|
|
defines various aspects about a chip, including memory layout, interrupt map,
|
|
and register sets. SVD includes information such as default values and field
|
|
bits, all information we have thanks to the introspectability of Python.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>SVD2Rust: Generating Safe Accessors</h2>
|
|
<aside class="notes">
|
|
In addition to generating a reference manual for humans, we can generate an SVD
|
|
file that's usable in a wide variety of areas. For example, we can turn an SVD
|
|
file into a Rust Peripheral Access Crate (PAC) using `SVD2Rust`, giving us an
|
|
easy way to safely access all peripherals on a device.
|
|
</aside>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Renode: Fancy Register Logging</h2>
|
|
<aside class="notes">
|
|
We can also import this SVD file into an emulator such as Renode, which will
|
|
print out fields and flags that get accessed, giving us greater visibility into
|
|
what a program is doing.
|
|
</aside>
|
|
</section>
|
|
</div>
|
|
</div> <!-- class="reveal" -->
|
|
<!-- End of main presentation -->
|
|
|
|
<!-- Start of configuration section -->
|
|
<script src="lib/js/head.min.js"></script>
|
|
<script src="js/reveal.js"></script>
|
|
|
|
<script>
|
|
var presenter = !!Reveal.getQueryHash().s;
|
|
|
|
// More info https://github.com/hakimel/reveal.js#configuration
|
|
Reveal.initialize({
|
|
controls: presenter ? false : true,
|
|
progress: true,
|
|
history: true,
|
|
center: true,
|
|
controlsTutorial: presenter ? false : true,
|
|
|
|
slideNumber: presenter ? null : 'c/t',
|
|
|
|
// The "normal" size of the presentation, aspect ratio will be preserved
|
|
// when the presentation is scaled to fit different resolutions. Can be
|
|
// specified using percentage units.
|
|
width: 960,
|
|
height: 700,
|
|
|
|
// Factor of the display size that should remain empty around the content
|
|
margin: 0.1,
|
|
|
|
multiplex: {
|
|
url: 'https://p.xobs.io/',
|
|
id: '631bb3db6fbaea78',
|
|
secret: Reveal.getQueryHash().s || null
|
|
},
|
|
|
|
// Bounds for smallest/largest possible scale to apply to content
|
|
minScale: 0.02,
|
|
maxScale: 5.5,
|
|
|
|
transition: 'slide', // none/fade/slide/convex/concave/zoom
|
|
|
|
// More info https://github.com/hakimel/reveal.js#dependencies
|
|
dependencies: [
|
|
{ src: 'lib/js/classList.js', condition: function () { return !document.body.classList; } },
|
|
{ src: 'plugin/markdown/marked.js', condition: function () { return !!document.querySelector('[data-markdown]'); } },
|
|
{ src: 'plugin/markdown/markdown.js', condition: function () { return !!document.querySelector('[data-markdown]'); } },
|
|
{ src: 'plugin/highlight/highlight.js', async: true, callback: function () { hljs.initHighlightingOnLoad(); } },
|
|
{ src: 'plugin/search/search.js', async: true },
|
|
{ src: 'plugin/zoom-js/zoom.js', async: true },
|
|
{ src: 'plugin/notes/notes.js', async: true },
|
|
|
|
{ src: 'lib/js/socket.io.js', async: true },
|
|
{
|
|
src: presenter ?
|
|
'plugin/multiplex/master.js' :
|
|
'plugin/multiplex/client.js', async: true
|
|
},
|
|
]
|
|
});
|
|
</script>
|
|
</body>
|
|
|
|
</html>
|