Commit 30b72503 authored by Neel Gala's avatar Neel Gala
Browse files

updated docs

parent a1ea715f
......@@ -2,339 +2,12 @@
Chromite-M SoC
##############
.. contents:: Contents
This a mid-feature enabled `Chromite Core <https://gitlab.com/incoresemi/core-generators/chromite>`_ based SoC targetting FPGAs. This developed and maintained by InCore Semiconductors Pvt. Ltd.
Following are the list of currently supported FPGA boards/targets:
1. `Arty A7 100t <https://www.xilinx.com/products/boards-and-kits/1-w51quh.html>`_
Amongts the cheapest development boards with sufficient space to port the current design.
Options to buy from :
- `Digilent <https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/>`_
- `Amazon <https://www.amazon.in/Digilent-Artix-7-Development-Makers-Hobbyists/dp/B017BOBNEO?tag=googinhydr18418-21>`_
Requirements
============
The following set of installation instructions have been tried out on a Ubuntu 18.04 system. For other operating systems, please install the required dependency packages.
The following set of tools will be required:
1. `Bluespec Compiler <https://github.com/B-Lang-org/bsc>`_: This is required to compile the BSV based soc, core, and other devices to Verilog.
2. Python3.7: Python 3.7 is required to configure compilation macros and clone dependencies.
3. `Verilator <https://www.veripool.org/projects/verilator/wiki/Installing>`_: Verilator is required for simulation purposes. Those not interested in simulation **can skip** installing this tool
4. `RISC-V Toolchain <https://github.com/riscv/riscv-gnu-toolchain>`_: You will need to install the RISC-V GNU toolchain to be able to compile programs that can run on Chromite.
5. `RISC-V OpenOCD <https://github.com/riscv/riscv-openocd>`_: ChromiteM SoC has a JTAG based debugger that provides access to the gdb interface. For gdb to be able to communicate to the processor, OpenOCD is required.
6. Miniterm: Miniterm is required for communication to the debug port on the FPGAs.
7. `Vivado <https://www.xilinx.com/support/download.html>`_: Xilinx Vivado is required to generate bitstream and program you FPGA.
Open Bluespec Compiler
----------------------
An open-source version of the Bluespec Compiler is available `here <https://github.com/B-Lang-org/bsc>`_. To install BSC:
Install required dependencies:
.. code-block:: bash
$ sudo apt-get install ghc libghc-regex-compat-dev libghc-syb-dev \
libghc-old-time-dev libfontconfig1-dev libx11-dev libxft-dev flex bison \
tcl-dev tk-dev libfontconfig1-dev libx11-dev libxft-dev gperf iverilog \
For Debian 8, Debian 9, Ubuntu 16.04, and Ubuntu 18.04, install the following:
.. code-block:: bash
$ sudo apt-get install itcl3-dev itk3-dev
For Debian 10 and later, and Ubuntu 19.04:
.. code-block:: bash
$ sudo apt-get install tk-itcl4-dev tk-itk4-dev
Clone and install BSC. For example, if you would like to install BSC at /tools/bsc/ :
.. code-block:: bash
$ git clone --recursive https://github.com/B-Lang-org/bsc
$ cd bsc
$ make PREFIX=/tools/bsc/
Add the BSC bin folder to your $PATH variable by appending the following line in your .bashrc or .cshrc:
.. code-block:: bash
$ export PATH=$PATH:/tools/bsc/inst/bin
**Note**: The latest compiler has been tested and known to work for Ubuntu
18.04. Also a binary built on 18.04 will not work on 16.04. It is suggested you do a fresh install for 16.04.
Python
------
You can either choose to directly install Python3.7 (`Ubuntu <https://linuxize.com/post/how-to-install-python-3-7-on-ubuntu-18-04/>`_, `Centos <https://tecadmin.net/install-python-3-7-on-centos/>`_) or use `PyEnv <https://realpython.com/intro-to-pyenv/>`_ (recommended)
Verilator
---------
While we support commercial Verilog simulators, our entire verification and simulation environments
are heavily driven by Verilator, and suggest you install Verilator as well.
.. code-block:: bash
$ sudo apt-get install git make autoconf g++ flex bison
$ git clone https://git.veripool.org/git/verilator
$ cd verilator
$ git checkout stable
$ autoconf
$ ./configure
$ make
$ sudo make install
RISC-V Toolchain
----------------
To install riscv-gnu-toolchain, first clone the repository:
.. code-block:: bash
$ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
On Ubuntu, the required dependencies can be installed by executing the following command:
.. code-block:: bash
$ sudo apt-get install autoconf automake autotools-dev curl python3 libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
On Fedora/CentOS OS, the required dependencies can be installed by executing the following command:
.. code-block:: bash
$ sudo yum install autoconf automake python3 libmpc-devel mpfr-devel gmp-devel gawk bison flex texinfo patchutils gcc gcc-c++ zlib-devel expat-devel
To install the newlib cross-compiler, first pick an install path. If you choose, say, /tools/riscv-newlib, then run the following commands:
.. code-block:: bash
$ export RISCV=/tools/riscv-newlib
$ ./configure --prefix=$RISCV --with-arch=rv64imac --with-abi=lp64 --with-cmodel=medany
$ make
Add the RISC-V Newlib compiler bin folder to your $PATH variable by appending the following line in your .bashrc or .cshrc:
.. code-block:: bash
export PATH=$PATH:/tools/riscv-newlib/bin
You should now be able to use riscv64-unknown-elf-gcc and it's cousins.
RISC-V OpenOCD
--------------
To install RISC-V OpenOCD, run:
.. code-block:: bash
$ git clone https://github.com/riscv/riscv-openocd --recursive
$ cd riscv-openocd
$ ./configure --enable-jlink --enable-remote-bitbang --enable-jtag_vpi --enable-ftdi --prefix=$RISCV
$ make
$ sudo make install
Miniterm
--------
To install Miniterm, run:
.. code-block:: bash
$ sudo apt-get install python-serial
Vivado
------
Xilinx Vivado is required to generate bitstream and program you FPGA.
1. Create an account on Xilinx (https://www.xilinx.com/registration/create-account.html) and download the Vivado Design Suite 2019.2 Linux Unified Installer (https://www.xilinx.com/member/forms/download/xef.html?filename=Xilinx_Unified_2019.2_1106_2127_Lin64.bin).
2. Run the Xilinx unified installer
.. code-block:: bash
$ chmod +x Xilinx_Unified_2019.2_1106_2127_Lin64.bin
$ ./Xilinx_Unified_2019.2_1106_2127_Lin64.bin
3. Install Vivado Design Suite HLx with the default settings that are present in the installer.
4. Install Xilinx cable drivers. Assuming, you set the install path in the previous step as /tools/Xilinx, run the following commands:
.. code-block:: bash
$ cd /tools/Xilinx/Vivado/2019.2/data/xicom/cable_drivers/lin64/install_script/install_drivers
$ sudo ./install_drivers
5. Add the Vivado binary path to your $PATH variable by appending the following line in your .bashrc or .cshrc:
.. code-block:: bash
export PATH=$PATH:/tools/Xilinx/Vivado/2019.2/bin:/tools/Xilinx/SDK/2018.3/bin
6. Add Vivado board files for Digilent FPGA boards:
.. code-block:: bash
$ git clone https://github.com/Digilent/vivado-boards.git
$ sudo cp -r vivado-boards/new/board_files /tools/Xilinx/Vivado/2019.2/data/boards/board_files
QuickStart
==========
Building the FPGA Bitstream
---------------------------
Perform the following steps to generate the bit-stream
1. Clone the repository:
.. code-block:: bash
$ git clone https://gitlab.com/incoresemi/fpga_ports/chromitem_soc.git
$ cd chromitem_soc
2. Configure the FPGA target: you need to edit only the `board_alias` field in the file chromitem.yaml. This field takes an alias name of the board you are targeting. Following if the list of currently supported fields:
- arty100t
3. Run the configuration script:
.. code-block:: bash
$ python -m configure.main
4. Generate Verilog: Change `<jobs>` to the number of parallel threads you want to use for the build.
.. code-block:: bash
$ make -j<jobs> generate_verilog
5. Build bitstream:
.. code-block:: bash
$ make ip_build fpga_build
6. Burn the bitstream on the FPGA
Connecting Host to FPGA
-----------------------
*NOTE: The following steps require that you have installed the RISC-V Gnu toolchain on your host machine.*
Open a new terminal to connect the serial the port as console:
.. code-block:: bash
$ sudo miniterm /dev/ttyUSB1 19200
Open another terminal and run the following command with a parameter ``EXE`` set to be path to the executable that you want to load. For example:
.. code-block:: bash
$ make connect_gdb EXE=sw/output/hello.riscv
On pressing the `reset-button` on your board the following should pop up on the console:
.. code-block:: bash
CCCCCCCCCCCCCCCCCC
CCCCCCCCC CCCCCCCC
CCCCCC CCCCCCC CCCCC
CCCCC CCCCCCCCCC CCCCC
CCCC CCCCCC CCCC
CCCC CCCCC CCC
CCCC CCCC CCCCCCC
CCCC CCCC CCCCCC
CCC CCCC CCCCC
CCCC CCC CCC
CCC CCCC CCC
CCC CCC CCC CCC
CCC CCC CCC CCC
CCC CCC CCC CCC
CCC CCCC CCCC CCCC
CCCC CCC CCCC CCC
CCC CCC CCCCC CCCC
CCC CCCC CCCCCCCC CCCC
CCCC CCCCC CCCCCC CCCCC
CCCCC CCCCC CCCCC CCC
CCCC CCCCCCCCCCCCCCCCCCCC CCCCC
CCCCC CCCCCCCCCCCCCCC CCCCC
CCCCCCC CCC CCCCCC
CCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCC
Chromite M SoC
Copyright (c) 2020 InCore Semiconductors
You can now use the GDB to load programs and execute them on the processor.
To load and execute a program in gdb, type ``load`` on the gdb prompt, followed by ``c``.
SoC Structure:
==============
Block Diagram:
--------------
The diagram below shows the overall structure of the SoC:
.. figure:: docs/ChromiteM.png
:width: 350px
Memory Map
----------
*NOTE: Base and Bound addresses are inclusive*
========= ============ =============
Device Base Address Bound Address
========= ============ =============
DebugROM 0x0000_0100 0x0000_010F
ROM 0x0001_0000 0x0001_0FFF
UART0 0x0001_1300 0x0001_13FF
UART1 0x0001_1400 0x0001_14FF
GPIO 0x0003_0000 0x0003_00FF
CLINT 0x0200_0000 0x0200_BFFF
PLIC 0x0C00_0000 0x0FFF_FFFF
OCM 0x1000_0000 0x1000_FFFF
DDR 0x8000_0000 0x8FFF_FFFF
Open 0x9000_0000 0xFFFF_FFFF
========= ============ =============
More details of each device is available in the ``docs/ip_blocks.pdf``
The Chromite M SoC is amongst InCore’s first No-Cost Eval SoC on FPGA based on the Chromite core
generator. This SoC is targetted for IoT and Industrial class applications requiring a 64-bit
micro controller.
The documentation of the project is built using sphinx.
For HTML version click `here<>`_
For PDF version click `here<>`_
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = C-Class Core Gen
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
/* -- Extra CSS styles for Zephyr content (RTD theme) ----------------------- */
/* make the page width fill the window */
.wy-nav-content {
max-width: none;
}
/* pygments tweak for white-on-black console */
/* hold off on this change for now
.highlight-console .highlight {
background-color: black;
}
.highlight-console .highlight .go, .highlight-console .highlight .gp {
color: white;
}
.highlight-console .highlight .hll {
background-color: white;
}
.highlight-console .highlight .hll .go, .highlight-console .highlight .hll .gp {
color: black;
font-weight: bold;
}
*/
/* tweak doc version selection */
.rst-versions {
position: static !important;
}
.rst-versions .rst-current-version {
padding: 5px;
background-color: #2980B9;
color: #80FF80;
}
.rst-versions .rst-other-versions {
padding: 5px;
}
div.rst-other-versions dl {
margin-bottom: 0;
}
/* tweak spacing after a toctree, fixing issue from sphinx-tabs */
.toctree-wrapper ul, ul.simple ol.simple {
margin-bottom: 24px !important;
}
/* code block highlight color in rtd changed to lime green, no no no */
.rst-content tt.literal, .rst-content code.literal, .highlight {
background: #f0f0f0;
}
.rst-content tt.literal, .rst-content code.literal {
color: #000000;
}
/* code literal links should be blue, and purple after visiting */
a.internal code.literal {
color: #2980B9;
}
a.internal:visited code.literal {
color: #9B59B9;
}
/* Make the version number more visible */
.wy-side-nav-search>div.version {
color: rgba(255,255,255,1);
}
/* squish the space between a paragraph before a list */
div > p + ul, div > p + ol {
margin-top: -20px;
}
/* squish space before an hlist in a list */
li table.hlist {
margin-top: -10px;
margin-bottom: 5px;
}
/* add some space before the figure caption */
p.caption {
# border-top: 1px solid;
margin-top: 1em;
}
/* decrease line leading a bit, 24px is too wide */
p {
line-height: 22px;
}
/* add a colon after the figure/table number (before the caption) */
span.caption-number::after {
content: ": ";
}
p.extrafooter {
text-align: right;
margin-top: -36px;
}
table.align-center {
display: table !important;
}
/* put the table caption at the bottom, as done for figures */
table {
caption-side: bottom;
}
.code-block-caption {
color: #000;
font: italic 85%/1 arial,sans-serif;
padding: 1em 0;
text-align: center;
}
/* make .. hlist:: tables fill the page */
table.hlist {
width: 95% !important;
table-layout: fixed;
}
/* override rtd theme white-space no-wrap in table heading and content */
th,td {
white-space: normal !important;
}
/* dbk tweak for doxygen-generated API headings (for RTD theme) */
.rst-content dl.group>dt, .rst-content dl.group>dd>p {
display:none !important;
}
.rst-content dl.group {
margin: 0 0 12px 0px;
}
.rst-content dl.group>dd {
margin-left: 0 !important;
}
.rst-content p.breathe-sectiondef-title {
text-decoration: underline; /* dbk for API sub-headings */
font-size: 1.25rem;
font-weight: bold;
margin-bottom: 12px;
}
.rst-content div.breathe-sectiondef {
padding-left: 0 !important;
}
/* doxygenXX item color tweaks, light blue background with dark blue top border */
.rst-content dl:not(.docutils) dl dt, dl:not(.docutils,.rst-other-versions) dt {
background: #e7f2fa !important;
border-top: none !important;
border-left: none !important; */
}
/* tweak display of option tables to make first column wider */
col.option {
width: 25%;
}
/* tweak format for <kbd> (:kbd:`F10`) */
kbd
{
-moz-border-radius:3px;
-moz-box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
-webkit-border-radius:3px;
-webkit-box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
background-color:#f7f7f7;
border:1px solid #ccc;
border-radius:3px;
box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
color:#333;
display:inline-block;
font-family:Arial,Helvetica,sans-serif;
font-size:11px;
line-height:1.4;
margin:0 .1em;
padding:.1em .6em;
text-shadow:0 1px 0 #fff;
}
/* home page grid display */
.grid {
list-style-type: none !important;
display: -webkit-box;
display: -ms-flexbox;
display: flex;
-ms-flex-wrap: wrap;
flex-wrap: wrap;
-webkit-box-pack: center;
-ms-flex-pack: center;
justify-content: center;
margin: 1rem auto;
max-width: calc((250px + 2rem) * 4);
}
.grid-item {
list-style-type: none !important;
-webkit-box-flex: 0;
-ms-flex: 0 0 auto;
flex: 0 0 auto;
width: 200px;
text-align: center;
margin: 1rem;
}
.grid-item a {
display: block;
width: 200px;
height: 200px;
padding: 20px;
display: -webkit-box;
display: -ms-flexbox;
display: flex;
-webkit-box-orient: vertical;
-webkit-box-direction: normal;
-ms-flex-direction: column;
flex-direction: column;
-webkit-box-pack: center;
-ms-flex-pack: center;
justify-content: center;
-webkit-box-align: center;
-ms-flex-align: center;
align-items: center;
border: 1px solid #c6cbce;
background-color: #1ab4e7;
color: white;
}
.grid-item h2 {
font-size: 1.1rem;
}
.grid-item img {
margin-bottom: 1.1rem;
max-width: 75%;
}
.grid-item a:hover {
background-color: #1892BA;
color: white;
}
.grid-item p {
margin-top: 0.5rem;
color: #333e48;
}
.grid-icon {
line-height: 1.8;
font-size: 4rem;
color: white;
}
/* add a class for multi-column support
* in docs to replace use of .hlist with
* a .. rst-class:: rst-columns
*/
.rst-columns {
column-width: 18em;