# Resources and Specifications

This page aims to collect all the resources and specifications we need
in one place for quick access. We will try our best to keep links here
up-to-date. Feel free to add more links here.

[[!toc  ]]

# OpenPOWER ISA

* <https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0>
* <https://openpowerfoundation.org/?resource_lib=ibm-power-isa-version-2-07-b>

# RISC-V Instruction Set Architecture

**PLEASE UPDATE** - we are no longer implementing full RISCV, only user-space
RISCV

The Libre RISC-V Project is building a hybrid CPU/GPU SoC. As the name
of the project implies, we will be following the RISC-V ISA I due to it
being open-source and also because of the huge software and hardware
ecosystem building around it. There are other open-source ISAs but none
of them have the same momentum and energy behind it as RISC-V.

To fully take advantage of the RISC-V ecosystem, it is important to be
compliant with the RISC-V standards. Doing so will allow us to to reuse
most software as-is and avoid major forks.

* Official compiled PDFs of RISC-V ISA Manual:
  <https://github.com/riscv/riscv-isa-manual/releases/latest>
* Working draft of the proposed RISC-V Bitmanipulation extension:
  <https://github.com/riscv/riscv-bitmanip/blob/master/bitmanip-draft.pdf>
* RISC-V "V" Vector Extension:
  <https://riscv.github.io/documents/riscv-v-spec/>

Note: As far as I know, we aren't using the RISC-V V Extension directly
at the moment. However, there are many wiki pages that make a reference
to the V extension so it would be good to include it here as a reference
for comparative/informative purposes with regard to Simple-V.

# IEEE Standard for Floating-Point Arithmetic (IEEE 754)

Almost all modern computers follow the IEEE Floating-Point Standard. Of
course, we will follow it as well for interoperability.

* IEEE 754-2019: <https://standards.ieee.org/standard/754-2019.html>

Note: Even though this is such an important standard used by everyone,
it is unfortunately not freely available and requires a payment to
access. However, each of the Libre RISC-V members already have access
to the document.

# Khronos Standards

The Khronos Group creates open standards for authoring and acceleration
of graphics, media, and computation. It is a requirement for our hybrid
CPU/GPU to be compliant with these standards *as well* as with IEEE754,
in order to be commercially-competitive in both areas: especially Vulkan
and OpenCL being the most important. SPIR-V is also important for the
Kazan driver.

Thus the [[zfpacc_proposal]] has been created which permits runtime dynamic
switching between different accuracy levels, in userspace applications.

**SPIR-V Main Page <https://www.khronos.org/registry/spir-v/>**

* SPIR-V 1.5 Specification Revision 1:
  <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html>
* SPIR-V OpenCL Extended Instruction Set:
  <https://www.khronos.org/registry/spir-v/specs/unified1/OpenCL.ExtendedInstructionSet.100.html>
* SPIR-V GLSL Extended Instruction Set:
  <https://www.khronos.org/registry/spir-v/specs/unified1/GLSL.std.450.html>

**Vulkan Main Page <https://www.khronos.org/registry/vulkan/>**

* Vulkan 1.1.122:
  <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/index.html>

**OpenCL Main Page <https://www.khronos.org/registry/OpenCL/>**

* OpenCL 2.2 API Specification:
  <https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html>
* OpenCL 2.2 Extension Specification:
  <https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_Ext.html>
* OpenCL 2.2 SPIR-V Environment Specification:
  <https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_Env.html>

Note: We are implementing hardware accelerated Vulkan and
OpenCL while relying on other software projects to translate APIs to
Vulkan. E.g. Zink allows for OpenGL-to-Vulkan in software.

# Graphics and Compute API Stack

I found this informative post that mentions Kazan and a whole bunch of
other stuff. It looks like *many* APIs can be emulated on top of Vulkan,
although performance is not evaluated.

<https://synappsis.wordpress.com/2017/06/03/opengl-over-vulkan-dev/>

# Various POWER Communities
 - [An effort to make a 100% Libre POWER Laptop](https://www.powerpc-notebook.org/en/)
   I still can't figure out if this chip is POWER8 or POWER9. Please verify!
 - [Power Progress Community](https://www.powerprogress.org/campaigns/donations-to-all-the-power-progress-community-projects/]
   Supporting/Raising awareness of various POWER related open projects on the FOSS
   community
 - [OpenPOWER](https://openpowerfoundation.org)
   Promotes and ensure compliance with the Power ISA amongst members.
 - [OpenCapi](https://opencapi.org)
   High performance interconnect for POWER machines. One of the big advantages
   of the POWER architecture. Notably more performant than PCIE Gen4, and is
   designed to be layered on top of the physical PCIE link.

# Free Silicon Conference

The conference brought together experts and enthusiasts who want to build
a complete Free and Open Source CAD ecosystem for designing analog and
digital integrated circuits.  The conference covered the full spectrum of
the design process, from system architecture, to layout and verification.

* <https://wiki.f-si.org/index.php/FSiC2019#Foundries.2C_PDKs_and_cell_libraries>

* LIP6's Coriolis - a set of backend design tools:
  <https://www-soc.lip6.fr/equipe-cian/logiciels/coriolis/>

Note: The rest of LIP6's website is in French, but there is a UK flag
in the corner that gives the English version.

* KLayout - Layout viewer and editor: <https://www.klayout.de/>

# The OpenROAD Project

OpenROAD seeks to develop and foster an autonomous, 24-hour, open-source
layout generation flow (RTL-to-GDS).

* <https://theopenroadproject.org/>

# Other RISC-V GPU attempts

* <https://fossi-foundation.org/2019/09/03/gsoc-64b-pointers-in-rv32>

* <http://bjump.org/manycore/>

* <https://resharma.github.io/RISCV32-GPU/>

TODO: Get in touch and discuss collaboration

# Tests, Benchmarks, Conformance, Compliance, Verification, etc.

## RISC-V Tests

RISC-V Foundation is in the process of creating an official conformance
test. It's still in development as far as I can tell.

* //TODO LINK TO RISC-V CONFORMANCE TEST

## IEEE 754 Tests

IEEE 754 has no official tests for floating-point but there are several
well-known third party tools to check such as John Hauser's SoftFloat
and TestFloat.

* <http://www.jhauser.us/arithmetic/>

Jacob is also making a Rust library to check IEEE 754 operations.

* <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2019-September/002737.html>

A cool paper I came across in my research is "IeeeCC754++ : An Advanced
Set of Tools to Check IEEE 754-2008 Conformity" by Dr. Matthias Hüsken.

* Direct link to PDF:
  <http://elpub.bib.uni-wuppertal.de/servlets/DerivateServlet/Derivate-7505/dc1735.pdf>

## Khronos Tests

OpenCL Conformance Tests

* <https://github.com/KhronosGroup/OpenCL-CTS>

Vulkan Conformance Tests

* <https://github.com/KhronosGroup/VK-GL-CTS>

MAJOR NOTE: We are **not** allowed to say we are compliant with any of
the Khronos standards until we actually make an official submission,
do the paperwork, and pay the relevant fees.

## Formal Verification

Formal verification of Libre RISC-V ensures that it is bug-free in
regards to what we specify.  Of course, it is important to do the formal
verification as a final step in the development process before we produce
thousands or millions of silicon.

Some learning resources I found in the community:

* ZipCPU: <http://zipcpu.com/>

ZipCPU provides a comprehensive tutorial for beginners and many exercises/quizzes/slides: <http://zipcpu.com/tutorial/>


* Western Digital's SweRV CPU blog (I recommend looking at all their posts): <https://tomverbeure.github.io/>

<https://tomverbeure.github.io/risc-v/2018/11/19/A-Bug-Free-RISC-V-Core-without-Simulation.html>

<https://tomverbeure.github.io/rtl/2019/01/04/Under-the-Hood-of-Formal-Verification.html>

## Automation

* <https://www.ohwr.org/project/wishbone-gen>

# LLVM

## Adding new instructions:

* <https://archive.fosdem.org/2015/schedule/event/llvm_internal_asm/>

# Branch Prediction

* <https://danluu.com/branch-prediction/>


# Information Resources and Tutorials

This section is primarily a series of useful links found online

* FSiC2019 <https://wiki.f-si.org/index.php/FSiC2019>
* Fundamentals to learn to get started [[3d_gpu/tutorial]]
* <https://github.com/timvideos/litex-buildenv/wiki/LiteX-for-Hardware-Engineers>
* <https://jeffrey.co.in/blog/2014/01/d-flip-flop-using-migen/>
* <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2019-March/000705.html>
* <https://chisel.eecs.berkeley.edu/api/latest/chisel3/util/DecoupledIO.html>
* <http://www.clifford.at/papers/2016/yosys-synth-formal/slides.pdf>
* <http://blog.lambdaconcept.com/doku.php?id=migen:tutorial>
* Samuel's KC5 code <http://chiselapp.com/user/kc5tja/repository/kestrel-3/dir?ci=6c559135a301f321&name=cores/cpu>
* <https://chips4makers.io/blog/>
* <https://hackaday.io/project/7817-zynqberry>
* <https://wiki.f-si.org/index.php/FSiC2019>
* <https://github.com/efabless/raven-picorv32> - <https://efabless.com>
* <https://efabless.com/design_catalog/default>
* <https://toyota-ai.ventures/>
* <https://github.com/lambdaconcept/minerva>
* <https://en.wikipedia.org/wiki/Liskov_substitution_principle>
* <https://en.wikipedia.org/wiki/Principle_of_least_astonishment>
* <https://peertube.f-si.org/videos/watch/379ef007-40b7-4a51-ba1a-0db4f48e8b16>
* <https://github.com/riscv/riscv-sbi-doc/blob/master/riscv-sbi.md>
* <https://mshahrad.github.io/openpiton-asplos16.html>
* <https://wiki.f-si.org/index.php/The_Raven_chip:_First-time_silicon_success_with_qflow_and_efabless>
* <http://smallcultfollowing.com/babysteps/blog/2019/04/19/aic-adventures-in-consensus/>
* <http://www.crnhq.org/12-Skills-Summary.aspx?rw=c>
* <http://bugs.libre-riscv.org/buglist.cgi?columnlist=assigned_to%2Cbug_status%2Cresolution%2Cshort_desc%2Ccf_budget&f1=cf_nlnet_milestone&o1=equals&query_format=advanced&resolution=---&v1=NLnet.2019.02>
* <https://pdfs.semanticscholar.org/5060/4e9aff0e37089c4ab9a376c3f35761ffe28b.pdf>
* <http://www.acsel-lab.com/arithmetic/arith15/papers/ARITH15_Takagi.pdf>
* <https://youtu.be/o5Ihqg72T3c>
* <http://flopoco.gforge.inria.fr/>
* Fundamentals of Modern VLSI Devices <https://groups.google.com/a/groups.riscv.org/d/msg/hw-dev/b4pPvlzBzu0/7hDfxArEAgAJ>

# Analog Simulation

* <https://github.com/Isotel/mixedsim>
* <http://www.vlsiacademy.org/open-source-cad-tools.html>
* <http://ngspice.sourceforge.net/adms.html>
* <https://en.wikipedia.org/wiki/Verilog-AMS#Open_Source_Implementations>

# Libre-RISC-V Standards

This list auto-generated from a page tag "standards":

[[!inline pages="tagged(standards)" actions="no" archive="yes" quick="yes"]]

# Server setup

[[resources/server-setup/git-mirroring]]