mirror of https://github.com/efabless/caravel.git
224 lines
8.8 KiB
ReStructuredText
Executable File
224 lines
8.8 KiB
ReStructuredText
Executable File
.. raw:: html
|
|
|
|
<!---
|
|
# SPDX-FileCopyrightText: 2020 Efabless Corporation
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
-->
|
|
.. _getting-started:
|
|
|
|
Caravel Architecture
|
|
====================
|
|
|
|
Caravel is composed of the harness frame plus two wrappers for drop-in modules for the *management area* and *user project area*.
|
|
|
|
.. _harness-definition:
|
|
|
|
Harness Definition
|
|
------------------
|
|
|
|
The harness itself contains the clocking module, DLL, user ID,
|
|
housekeeping SPI, POR, and GPIO control.
|
|
|
|
GPIO handling moved out of management SoC and into SPI. SPI
|
|
gets a wishbone interface; the management SoC talks to the SPI
|
|
through wishbone, not by taking over the 4-pin SPI interface.
|
|
|
|
A new block like the ID has the mode at power-up for
|
|
each GPIO. Can be configured with a text file. SPI pins are
|
|
fixed for operation on startup.
|
|
|
|
On power-up, the SPI automatically configures the
|
|
GPIO. Manual load is possible from both the SPI and from the
|
|
wishbone bus.
|
|
|
|
All functions within the harness but outside the management SoC
|
|
are incorporated into one large module called "housekeeping".
|
|
This includes a number of registers for all the included
|
|
functions, with a "front door" SPI interface connected to the
|
|
padframe through GPIO pins 1 to 4, and a "back door" wishbone
|
|
interface connected to the management SoC. The management Soc
|
|
reserves the memory block at 0x26000000 for the
|
|
housekeeping module. The housekeeping module exchanges data
|
|
with the management SoC via an interface that uses the byte-
|
|
wide SPI register data. A small state machine reads four
|
|
contiguous wishbone addresses and an address decoder determines
|
|
the corresponding SPI register. The state machine stalls the
|
|
SoC until all four bytes have been handled before returning the
|
|
acknowledge signal.
|
|
|
|
.. _management-area:
|
|
|
|
Management Area
|
|
--------------
|
|
|
|
The management area is a drop-in module implemented as a separate repo.
|
|
It typically includes a RISC-V based SoC that includes a number of peripherals like timers, uart, and gpio.
|
|
The management area runs firmware that can be used to:
|
|
|
|
- Configure User Project I/O pads
|
|
- Observe and control User Project signals (through on-chip logic
|
|
analyzer probes)
|
|
- Control the User Project power supply
|
|
|
|
The management area implements SRAM for the management SoC.
|
|
|
|
The default instantiation for the management core can be found `here <https://github.com/efabless/caravel_mgmt_soc_litex>`__ .
|
|
See documentation of the management core for further details.
|
|
|
|
.. _user-project-area:
|
|
|
|
User Project Area
|
|
--------------
|
|
|
|
This is the user space. It has a limited silicon area ``2.92mm x 3.52mm`` as well as a fixed number of I/O pads ``38`` and power pads ``4``.
|
|
|
|
The user space has access to the following utilities provided by the management SoC:
|
|
|
|
- ``38`` IO Ports
|
|
- ``128`` Logic analyzer probes
|
|
- Wishbone port connection to the management SoC wishbone bus.
|
|
|
|
|
|
Quick Start for User Projects
|
|
=============================
|
|
|
|
Your area is the full user space, so feel free to add your
|
|
project there or create a different macro and harden it separately then
|
|
insert it into the ``user_project_wrapper`` for digital projects or insert it
|
|
into ``user_project_analog_wrapper`` for analog projects.
|
|
|
|
.. _digital-user-project:
|
|
|
|
Digital User Project
|
|
--------------------
|
|
|
|
If you are building a digital project for the user space, check a sample project at `caravel_user_project <https://github.com/efabless/caravel_user_project>`__.
|
|
|
|
If you will use OpenLANE to harden your design, go through the instructions in this `README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
|
|
|
|
Digital user projects should adhere the following requirements:
|
|
|
|
- Top module is named ``user_project_wrapper``
|
|
|
|
|
|
- The ``user_project_wrapper`` adheres to the pin order defined at `Digital Wrapper Pin Order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__.
|
|
|
|
|
|
- The ``user_project_wrapper`` adheres to the fixed design configurations at `Digital Wrapper Fixed Configuration <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__.
|
|
|
|
|
|
- The user project repository adheres to the `Required Directory Structure <#required-directory-structure>`__.
|
|
|
|
|
|
.. _analog-user-project:
|
|
|
|
Analog User Project
|
|
------------------
|
|
|
|
If you are building an analog project for the user space, check a sample project at `caravel_user_project_analog <https://github.com/efabless/caravel_user_project_analog>`__.
|
|
|
|
Analog user projects should adhere the following requirements:
|
|
|
|
- Top module is named ``user_analog_project_wrapper``
|
|
|
|
- The ``user_analog_project_wrapper`` uses the `empty analog wrapper <https://github.com/efabless/caravel/blob/master/mag/user_analog_project_wrapper_empty.mag>`__.
|
|
|
|
- The ``user_analog_project_wrapper`` adheres to the same pin order and placement of the `empty analog wrapper <https://github.com/efabless/caravel/blob/master/mag/user_analog_project_wrapper_empty.mag>`__.
|
|
|
|
------
|
|
|
|
IMPORTANT
|
|
^^^^^^^^^
|
|
|
|
Please make sure to run ``make compress`` before committing anything to
|
|
your repository. Avoid having 2 versions of the
|
|
``gds/user_project_wrapper.gds`` one compressed and the
|
|
other not compressed.
|
|
|
|
For information on tooling and versioning, please refer to `tool-versioning.rst <./docs/source/tool-versioning.rst>`__.
|
|
|
|
-----
|
|
|
|
Required Directory Structure
|
|
============================
|
|
|
|
- ``gds/`` : includes all the gds files used or produced from the
|
|
project.
|
|
- ``def`` : includes all the def files used or produced from the
|
|
project.
|
|
- ``lef/`` : includes all the lef files used or produced from the
|
|
project.
|
|
- ``mag/`` : includes all the mag files used or produced from the
|
|
project.
|
|
- ``maglef`` : includes all the maglef files used or produced from the
|
|
project.
|
|
- ``spi/lvs/`` : includes all the spice files used or produced from the
|
|
project.
|
|
- ``verilog/dv`` : includes all the simulation test benches and how to
|
|
run them.
|
|
- ``verilog/gl/`` : includes all the synthesized/elaborated netlists.
|
|
- ``verilog/rtl`` : includes all the Verilog RTLs and source files.
|
|
- ``openlane/<macro>/`` : includes all configuration files used to
|
|
run openlane on your project.
|
|
- ``info.yaml``: includes all the info required in `this
|
|
example <https://github.com/efabless/caravel/blob/master/info.yaml>`__. Please make sure that you are pointing to an
|
|
elaborated caravel netlist as well as a synthesized
|
|
gate-level-netlist for the `user_project_wrapper`
|
|
|
|
|
|
**NOTE:**
|
|
|
|
If you're using openlane to harden your design, the ``verilog/gl`` ``def/`` ``lef/`` ``gds/`` ``mag`` ``maglef`` directories should
|
|
be automatically populated by openlane.
|
|
|
|
.. _additional-material:
|
|
|
|
Additional Material
|
|
===============
|
|
|
|
.. _mpw-two:
|
|
|
|
MPW Two
|
|
--------
|
|
|
|
- `Open MPW Program - MPW-TWO Walkthrough <https://www.youtube.com/watch?v=jBrBqhVNgDo>`__
|
|
- `MPW Two Shuttle Program <https://efabless.com/open_shuttle_program/2>`__
|
|
|
|
.. _mpw-one:
|
|
|
|
MPW One
|
|
--------------
|
|
|
|
- `Caravel Legacy Repo (previous version used for MPW-ONE) <https://github.com/efabless/caravel_mpw-one>`__
|
|
- `Caravel User Project Features -- What are the utilities provided by caravel to the user project ? <https://youtu.be/zJhnmilXGPo>`__
|
|
- `Aboard Caravel -- How to integrate your design with Caravel? <https://youtu.be/9QV8SDelURk>`__
|
|
- `Things to Clarify About Caravel -- What versions to use with Caravel? <https://youtu.be/-LZ522mxXMw>`__
|
|
- `45 Chips in 30 Days: Open Source ASIC at its best! <https://www.youtube.com/watch?v=qlBzE27at6M>`__
|
|
|
|
Check `mpw-one-final <https://github.com/efabless/caravel/tree/mpw-one-final>`__ for the caravel used for the mpw-one tapeout.
|
|
|
|
> :warning: You don't need to integrate your design with Caravel GDS for **MPW two**. Running ``make ship`` is no longer required.
|
|
|
|
|
|
.. |License| image:: https://img.shields.io/github/license/efabless/caravel
|
|
:alt: GitHub license - Apache 2.0
|
|
:target: https://github.com/efabless/caravel
|
|
.. |Documentation Status| image:: https://readthedocs.org/projects/caravel-harness/badge/?version=latest
|
|
:alt: ReadTheDocs Badge - https://caravel-harness.rtfd.io
|
|
:target: https://caravel-harness.readthedocs.io/en/latest/?badge=latest
|
|
.. |Build Status| image:: https://travis-ci.com/efabless/caravel.svg?branch=master
|
|
:alt: Travis Badge - https://travis-ci.org/efabless/caravel
|
|
:target: https://travis-ci.com/efabless/caravel |