openframe_timer_example

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   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.

Notes on building the caravel_openframe_project:
=================================================
Tim Edwards
May 1, 2023 to August 29, 2023

This is an example project of a picoRV32 processor and SoC that
roughly matches the management core used on first Efabless SkyWater
OpenMPW.  However, this project is intended to synthesize into the
project area of the Caravel Openframe.

The "NOTES" file is a collection of notes I made while trying
to get the openlane build to work cleanly from end to end.
See the README file for the final set of step-by-step instructions
for the build.

=======================================

Build notes:

(1) Building using local (not containerized) OpenROAD and Openlane.
    OpenROAD was pulled from git and compiled.
    Required libboost to be compiled and installed from source,
	because cmake insisted on a boost library newer than that
	supported by my OS.
    Openlane was pulled from git and built.

(2) cd to openlane/openframe_project_wrapper

(3) Quick experimental build:	~/gits/openlane/flow.tcl
    Determined that switch "-ignore_mismatches" is required to
	bypass the error and exit caused by my tool versions.

(4) Do:  ~/gits/openlane/flow.tcl -ignore_mismatches
    Needed to fix one syntax issue;  now it complains I need PDK_ROOT set

(5) Do:
	setenv PDK_ROOT /usr/share/pdk
	setenv PDK sky130A
	~/gits/openlane/flow.tcl -ignore_mismatches

(6) Removed CLOCK_TREE_SYNTH from config.json because it is apparently
	deprecated.

(7) "click" module needed for python3.  But it exists.  Why does the
	odbpy/lefutil.py script fail, then?
    Hacked my way around this by adding
	import sys
	sys.path.append('/usr/lib/python3.10/site-packages')
	import click
    to the lefutil.py script.  But there must be a proper way to configure
    the python path correctly for openroad.

(8) This actually ran. . . verilator (synthesis step 1) found errors, so
    need to fix those.  Except. . .  failed to generate report due to
    failure to load module "report", which is another path issue
	('/usr/lib64/python3.10/site-packages')
    Except this time, it still doesn't work.  Can import "report", can
    do "from report import report" but cannot do "from report.report import
    Report"---no such thing.  Need to pip install "reports" ???
    (in /home/tim/gits/openlane/scripts/generate_reports.py)
    Ahh. . . It is not a standard python package but local to openlane.
    Also:  The underlying problem is that there is a python package "report"
    installed on my system, and this one is being preferred.
    Hack solution:  "pip uninstall" didn't work, so I just renamed "report"
    in the offending library directory so it won't be found.

    Back to the original issue:  see runs//logs/synthesis/verilator.log
    Problem---No defines.v, no OPENFRAME_IO_PADS defined.

    Wrong set of files in config.json.  defines.v appears twice and needs
    to be removed.

    Now verilator complains about all sorts of non-issues.  How to disable
    verilator?  Set RUN_VERILATOR to 0 in the config file.

(9) Synthesis fails on call to standard cell "sky130_fd_sc_hd__einvn_8".
    How to solve this?  Tried "STD_CELL_LIBRARY_OPT" but that didn't work.
    Setting "SYNTH_READ_BLACKBOX_LIB" worked.

(10) Now fails on the SRAM, which is not surprising.
    ---Added openframe_example.soc_mem.SRAM_0 and
    openframe_example.soc_mem.SRAM_1 to macro.cfg but presumably need more.
    ---Added filenames for the SRAM block to VERILOG_FILES_BLACKBOX, EXTRA_LEFS,
    and EXTRA_GDS_FILES (probably need EXTRA_LIBS, too).

(11) "$::env(PDK_ROOT)" doesn't work in the config.json file.
	"::env(PDK_ROOT)" doesn't work, either.  Punting for now and
	inserting full path.

(12) Now it complains there is no port "vssd1" on
	sky130_sram_2kbyte_1rw1r_32x512_8 of SRAM_1 in mem_wb.v.  What gives?
	Testing. . . it will also complain about vccd1 and about SRAM_0, just
	generates errors from the bottom of the file up for some reason.
	But is USE_POWER_PINS being changed between reading the library and
	reading the design?  But "SYNTH_USE_PG_PINS_DEFINES" is set to
	"USE_POWER_PINS".  Try not setting that?
	Okay, no good, so try *not* defining it in the netlists file (or
	rather, defining it only if SIM is defined). . . and bingo.

(13) "Out of bounds on some signals" error, need to check log file.
	Seems not happy about the OR'd bits in the array assignment
	assign gpio_all_dat_o[i] = |(gpio_dat_o[i][`OPENFRAME_IO_PADS-1:0]);
	??
	Disabled the out-of-bound check in openlane tcl_commands/checkers.tcl
	Next set of checks appears to be more relevant.
	Fixed all of them but there are "multiple driver" errors on tri-state
	buffers, so disabling the "check_synth_misc" check, too.

(14) Failed on "proc_rom"---This is a command in yosys/synth.tcl, and it seems
	that yosys fails to understand it.  Maybe by default yosys is being run
	from my original installed version which is a bit out of date?
	Commented "proc_rom" out of the synth script and continued.

(15) Failed because config file was set with SYNTH_ELABORATE_ONLY.  Fixed.

(16) Tried to read verilog of the SRAM;  failed to black-box it.  Maybe put back
	the original brackets in the blackbox definition in config.json?
	(Did not make a difference)
	Following suggestion and adding "/// sta-blackbox" to the verilog file,
	but that's in the PDK, so not a preferred solution.
	(Might also be because the "extra liberty files" setting was not in
	the config file?)

(17) Next error:  invalid command name "report_parasitic_annoation" in
	multi_corner.tcl.  Commenting the line
	(openlane/scripts/openroad/sta/multi_corner.tcl)
	Now is running STA, maybe successfully. . .
	Seems to have hung up on something.  Produced an output almost
	immediately, after which it is just grinding away.
	Ran 10 hours and is still going in the morning, so something is
	wrong.
	NOTE:  This happened on "report_clock_skew", and tracking that
	down to openroad/sta/multi_corner.tcl, there's a comment that
	says OpenROAD hangs if the "report_clock_skew" command is run
	on a clockless design.  Presumably there's something similar
	going on, like the clock isn't specified correctly.  Disabling
	the report for now.

(18) Floorplan---same issue with python paths for importing "click" as
	above (see (7)).  Needed in defutil.py, apply_def_template.py,
	manual_macro_place.py

(19) Floorplan---complains that some pins are not on the manufacturing
	grid, specifically por_l/porb_h/porb_l.  This comes from the
	DEF file at fixed_dont_change/openframe_project_wrapper.def.
	Magic shouldn't be putting things at off-grid positions!
	In fact, it shouldn't even be possible. . .  Except that
	distance units have been set at 1000, not 200.  But magic did,
	and generated non-integer entries in the DEF file to boot, so
	this will need to be investigated.  Actually, there were rather
	a lot of such entries in the file at 1/2 grid points.  I think
	that this is due to centerlines, and the DEF writer is not
	paying attention to the grid limit settings in "cifoutput"
	although it is assumed to be producing equivalent output.

(20) Macro placement:  Macros not found.  Used names
	"openframe_example.soc_mem.SRAM_0" (and "1") in macro.cfg.
	What should this be instead?
	Missing a hiearchy layer;  should be
	"openframe_example.soc_mem.mem.SRAM_0"
	After that. . . got all the way to step 7!

(21) Global placement:  "click" again. . .

(22) Detail placement failed during/after clock tree synthesis.
	Chances are good that this is due to the incorrect floorplan
	DEF (tracks and sites do not cover the entire die area as
	they should)?  Need to look at output.

	Result---The placement actually covers the area in spite of
	the incorrect list of tracks/sites, so that doesn't seem to
	be the underlying problem.

(23) Continuing 5/9/2023 after break due to travel.  Committed all work
	so here's a recap:
	Do:
	setenv PDK_ROOT /usr/share/pdk
	setenv PDK sky130A
	cd openlane/openframe_project_wrapper
	~/gits/openlane/flow.tcl -ignore_mismatches

	(had updated sky130A PDK and needed to redo the "/// sta-blackbox"
	comment line in sky130_sram_2kbyte_1rw1r_32x512_8.v)

(24) Continuing 8/11/2023 after the openlane team worked over this.
	Copied over all openlane configuration files.  The openlane
	flow has now been divided into multiple blocks (picoRV32 core,
	clock routing, DLL, and then the top level wrapper) which are
	hardened hierarchically.  Macros were added which connect to the
	VCCD1/VSSD1 busses (although preferably there should be additional
	connections to VCCD/VSSD and VCCD2/VSSD2 for robustness).

	Note that I am attempting to keep the *unbuilt* sources in the
	original "main" repository branch, while working on a build in
	a "build" branch.  It should be possible to keep a minimum set of
	files in the (committed) upstream repository while being able to
	generate the final layout through a series of known repeatable
	steps. 

(25) NOTE:  The issue with having to rewrite the openlane scripts for
	the "click" package is probably best resolved by running
	in a python virtual environment, even though I consider that
	solution akin to docker and dislike it immensely.

(26) Continuing 8/28/2023 after another hiatus.
	Testing with the following steps:
	(1) Setup
		setenv PDK_ROOT /usr/share/pdk
		setenv PDK sky130A
	(2) Synthesize the digital_locked_loop macro.
		cd openlane/digital_locked_loop
		~/gits/openlane/flow.tcl -ignore_mismatches

	    --> There is an immediate issue that verilator pulls all .v
		files from the PDK, and is catching the newly-added
		black-box files.  Temporarily renaming them to avoid
		a conflict.
	    --> Another issue is that  fakediode_2 is calling a base
		cell sky130_fd_sc_hd__diode that does not exist.
		Changing name to from diode to diode_2 (need to fix in
		the PDK install).
	    --> Same thing with fill_12 calling base cell fill that
		does not exist;  this one just needs to be deleted.
	    --> And verilator just seems to be overly eager to find
		errors where they don't exist.  Any way to turn it
		off??? (Yes---set env variable "RUN_VERILATOR" to 0)
	    --> Failed due to no SYNTH_CAP_LOAD defined?
		Defined it and set to 52 based on an entry in caravel.
		No idea what the units are. . .  Or why it needs to
		be defined (might need an openlane update).
	    --> Now stuck again with the "click" module issue, in
		io_place.py (fixed) and diodes.py (fixed) and
		wire_lengths.py (fixed) and power_utils.py (fixed)
	    --> Started step 30 (stream-out with klayout) but klayout
		isn't running in batch.  Why would you stream out with
		both klayout and magic?  Just exiting from klayout
		manually (but how to fix. . .  and is this step even
		needed?).
		Back-annotated note:  (1) No, the klayout step is not
		needed and exiting klayout continues without issue.
		(2) Failure to run klayout in batch mode is a self-
		inflicted problem caused by using a script to launch
		klayout but failing to handle arguments.  Reworked by
		adding the directory for klayout's shared object
		libraries to ld.so.conf.d and running ldconfig, and
		replacing the script with a symbolic link to the
		executable.
	    --> Step 37, cvc_rv does not exist.  I have the source, but
		it is not installed---and I cannot install it due to
		inscrutable errors.  (set env variable RUN_CVC = 0
		to disable)
	    --> Finally, the flow completed (although is it correct?)
		(there are max fanout violations reported.)

	(3) Synthesize the picosoc macro.
		cd openlane/picosoc
		~/gits/openlane/flow.tcl -ignore_mismatches

	    --> Cannot find LEF of digital_locked_loop.
		Copied the LEF file manually (but why isn't this done
		automatically?)
	    --> Cannot find GDS of digital_locked_loop.
		Copied the GDS file manually (but why isn't this done
		automatically?)
	    --> Need to disable verilator
	    --> Cannot find .lib of digital_locked_loop.
		None was created, so had to copy from the working files
		Back-annotated comment:  This can be corrected simply
		by changing STA_WRITE_LIB to 1.
	    --> Cannot find gl/.v file of digital_locked_loop
		Copied the .v file manually (but why isn't this done
		automatically?)
	    --> Needs SYNTH_CAP_LOAD defined (see above)
	    --> Yosys error: picorv32 redefined ??
		Added "ifndef PnR"..."endif" around file includes
	    --> Needs digital_locked_loop.min.spef in
		signoff/digital_locked_loop/openlane-signoff/spef/	
		(added nom and max for good measure)
	    --> Now running and spending extensive time in step 16
		(global routing resizer design optimizations)
		Letting it run. (Started 5:18pm)
	    --> And then it died on a totally obscure syntax error of
		a line in picosoc.nl.v "wire [38:0] \% Xz ;".  Seems
	  	to have been derived from the pnl.v line which has
		"wire [38:0] \J\xfd6\x88 ;".  Not clear where this
		comes from but tool updates (OpenROAD in particular)
		are probably in order (wanders off for several hours
		on a quest to rebuild OpenROAD. . .)
	    --> (Returns after finally coercing OpenROAD to compile
		again) Now I get a different obscure error earlier
		in the sequence:

		File "/home/tim/gits/openlane/scripts/odbpy/reader.py",
			line 37, in __init__
			odb.read_def(self.db, def_in)
		File "odb_py.py", line 9553, in read_def
		TypeError: in method 'read_def', argument 1 of type 'odb::dbTech *'

		Something has gone very wrong here and it is not clear
		to me what, other than that it was caused by recompiling
		OpenROAD.

(27) Continuing 8/29/2023 after updating OpenROAD *and* openlane.

	(1) Create python virtual environment this time to avoid issue
			with the "click" package.
		python3 -m venv ./venv
		./venv/bin/python3 -m pip install --upgrade --no-cache-dir -r \
			/home/tim/gits/openlane/requrements.txt
		source ./venv/bin/activate.csh
		--> This works!

	(2) Run ~/gits/openlane/flow.tcl -ignore_mismatches
		--> RUN_VERILATOR superceded by RUN_LINTER (fixed)
		--> yosys fails on command "proc_rom". . .
		    Need yosys update now. . . (Goes off and rebuilds yosys)

	(3) (Hey, I'm back) Trying again with yosys updated.
	    Run ~/gits/openlane/flow.tcl -ignore_mismatches
		--> Noted that SYNTH_CAP_LOAD is deprecated.  Not sure
		    why that didn't show up before. . . ?  Changed to
		    OUTPUT_CAP_LOAD as requested, for subsequent runs.
		--> Now running and at step 15 and going well so far.
		--> Now running and at step 26 and going well so far.
		--> Now running and at step 35 and going well so far.
		--> Success!		

(28) Now run the project wrapper:
	(Will presumably need to copy files from the picosoc synthesis
	 to the top level before this will work.)

	Copy picosoc LEF, GDS, .lib, and GL verilog;

		cd openlane/openframe_project_wrapper
		~/gits/openlane/flow.tcl -ignore_mismatches

		--> Need to also copy the GDS of vccd1_connection
		    and vssd1_connection from the "_work" branch.
		--> Apparently these files can't be compressed,
		    either.
		--> Also need gate-level .v files for vccd1 and
		    vssd1 connection.
		--> Forgot the picosoc SPEF files. (min, max, nom)
		--> Now running without problems.
		--> Observation:  "Generating lef with Magic" seems
		    to be taking a rather long time.  (But not
		    ridiculously long, so probably okay.)

	Final solution generated but there are hold violations at the
	typical corner.  (Single violation clk on gpio_in[38] to
	openframe_example/_34243_)

OpenFrame Project Example
=====================================

The OpenFrame Project Example is a user project designed to showcase how to use
the Caravel "OpenFrame" design, which is an alternative user project harness
chip that differs from the Caravel and Caravan designs by (1) having no integrated
SoC on chip, (2) allowing access to all GPIO controls, (3) maximizing the user
project area, and (4) minimizing the support circuitry to comprise only the
padframe, a power-on-reset circuit, and a digital ROM containing the 32-bit
project ID.  The padframe design and placement of pins matches the Caravel and
Caravan chips.  The pin types also remain the same, with power and ground pins
in the same positions, with the same power domains available.  Pins which
previously had functions connected with the CPU (flash controller interface,
SPI interface, UART) use the same GPIO pads but allocate them to
general-purpose I/O for any purpose.

One reason for choosing the Openframe harness is to implement an alternative
SoC or implement an SoC with the user project integrated into the same level
of hierarchy.  This project example demonstrates that approach, where the
VexRISC CPU from the Caravel and Caravan chips is replaced with a PicoRV32,
which is the same processor core that was used on the first Caravel design
from MPW-one.  To facilitate testing, the design maintains the same
special-purpose pins used by Caravel and Caravan, such as (critially) the
flash controller and housekeeping SPI, so that the chip after fabrication
will be fully compatible with the development board shipped by Efabless
with the chips.

The primary difference between this Openframe project example and the
original MPW-one Caravel design is that there is no user project in the
middle, since the whole thing is now the user project.  Interfaces that
existed between the SoC core and user project, such as the logic analyzer,
have no meaning in this context and are eliminated.  The Wishbone address
space to the user project is eliminated, but the design is free to add
any additional Wishbone modules at any valid memory map location.  The
GPIOs are no longer shared between the CPU and the user project.  Each
GPIO is therefore configured individually, with a separate Wishbone
interface connecting to each one for configuration and I/O.

Otherwise, this project example does not seek to provide additional
components above and beyond what was already on the Caravel harness chip,
which includes the flash controller, UART, an SPI master, two counter/timers,
housekeeping SPI, and digital locked loop (DLL).  It provides only one new
module that groups GPIO signals into a vector that can be written or read
at the same time;  that module recovers the function of simultaneous GPIO
reads and writes that was handled in Caravel and Caravan by the housekeeping
module, but was eliminated by moving GPIO configuration to individual
Wishbone interfaces.

This README file provides basic information about the project's features,
configurations, and usage.  Complete documentation can be found in the
file docs/caravel_openframe_datasheet.pdf.  The datasheet does not contain
information about architecting or hardening the design.

Table of Contents
-----------------
- Module Overview
- Designing
- Building
- Submitting
- Contributing
- License

Module Overview
---------------

The OpenFrame project example is built around the PicoRV32 CPU from YosysHQ,
specifically the version which utilizes the Wishbone interface to communicate
with various modules.  This project example includes the following IPs, listed
with their respective base addresses:

- RAM: 0x00000000
- FLASH: 0x10000000
- UART: 0x20000000
- GPIO: 0x21000000
- Counter Timer 0: 0x22000000
- Counter Timer 1: 0x23000000
- SPI Master: 0x24000000
- GPIO Vector: 0x25000000
- Flash Controller: 0x2D000000
- Debug Registers: 0x41000000

Additionally, the project includes a "housekeeping" module that is accessed
by SPI protocol for DLL configuration, chip information, and flash programming.
This IP is not accessible through the Wishbone bus in this version, but is
indirectly accessible by coupling internally to the SPI master.

Designing
---------

The main challenge of architecting an Openframe project is understanding
the GPIO pad interface, which is quite complicated.  The Caravel and
Caravan designs purposefully kept details away from the end user.  This
example presents a similar solution in which each GPIO pad is interfaced
by an independent Wishbone interface (gpio_wb.v).  Each GPIO has I/O
similar to the user project connections on Caravel and Caravan, but with
a four-signal interface that adds the input disable pin (cpu_gpio_ieb)
to the common three-pin interface with output disable (cpu_gpio_oeb),
output (cpu_gpio_out), and input (cpu_gpio_in).  The remaining configuration
options for the GPIO pad are handled through Wishbone writes.  The
Wishbone interface additionally allows the three I/O signals to be
overridden by an internal register value.

Any additions to the Wishbone bus need to be added to the Wishbone
address interpreter (intercon_wb.v).  Note that this has been done
differently for the GPIO modules so that all of the GPIO wishbone
instances (one per GPIO pin) can act as a single wishbone interface;
each instance decodes only its own address, and all GPIO instances
share the GPIO data bus and acknowledge signal.

Where on Caravel, the default configuration of each GPIO pin at power-up
is declared in a separate file, here the default configuration data is
kept as a parameter array (picosoc.v) and applied to each GPIO wishbone
instance.

The "cpu_gpio_*" pins on the GPIO wishbone interface (see above) define
a "standard function" for each GPIO pin (such as SPI master pins, UART
transmit/receive, etc.).  Since many of these GPIO do not change
configuration (are always either input or output), the input and output
disables, and sometimes the output value, are fixed constant high or
low.  For this purpose, each pad provides an individual pair of pins
"gpio_loopback_zero" and "gpio_loopback_one" that are placed next to
the pad and should be used for applying constant values to pad-related
signals.

The loopback constants can also be used to blanket disable specific
unneeded functions of the GPIO pins.  In openframe_project_wrapper.v,
they have been used to disable the obscure inputs "gpio_analog_*"
(an interface to a switched-capacitor analog bus pair) and
"gpio_holdover" (related to a sleep state that possibly cannot be
achieved given the wiring inside the padframe).

The hierarchy of the Openframe project is:

Top level:  openframe_project_wrapper.v.  This must always be the name
of the top level cell, as it is what gets integrated into the Openframe
design to create the completed chip.  The openframe_project_wrapper
module instantiates the SoC and ties off (or leaves unconnected) pins
unused by the SoC.

Second level:  picosoc.v.  This is the SoC definition.  It instantiates
all of the blocks of the SoC as Wishbone components:  The CPU
(picorv32_wb), the SPI flash controller (spimemio_wb), the UART
(simpleuart_wb), SRAM (mem_wb), and others.  It defines all of the
wiring to the I/Os.  It also defines a few modules that have not (by
design choice) been implemented as Wishbone components:  The
housekeeping module (housekeeping), the DLL (digital_locked_loop), and
the clock and reset routing and synchronization (clock_routing).

Third level:  All SoC modules.

Power domain considerations:

This design example connects the entire user project design to the
vccd1/vssd1 domain using power connection cells (with verilog,
layout, abstract, etc. views) that are treated as macros and placed
at the appropriate position in the layout to connect between the
padframe power pads and the power ring surrounding the synthesized
digital core.  In general, however, it is preferable to connect
together as many domains as possible to maximize the amount of
current delivered to the project and minimize the amount of I-R
drop from the pads to any point in the core.  The 3.3-5.0V domains
(vdda/vssa, vdda1/vssa1, vdda2/vssa2, vddio/vssio) should be kept
separate from the 1.8V domains (vccd/vssd, vccd1/vssd1, vccd2/vssd2),
but otherwise the user is encouraged to short together all the 1.8V
domains and optionally (if used) the 3.3V domains with the exception
of vddio/vssio, which is the ESD supply for the padframe and should
remain isolated.

Analog and mixed-signal designs:

Analog designs may make use of Openframe, but since there is no
Caravan-equivalent of Openframe with bare analog pads, any analog
signals in the Openframe design must connect to the GPIO pads, which
limits them to the voltage range of (vddio, vssio), and limits the
frequency to approximately 60MHz.  All GPIOs connected to analog
signals must have the input and output buffers disabled.

The two choices of connections for analog signals to a GPIO pad are
(1) the analog_io[] pins, which connect to the pad through a resistor
and are the preferred connection, having some ESD protection; and
(2) the analog_noesd_io[] pins, which connect directly to the pad and
are very ESD sensitive.  They should not be used unless the signal
in question cannot tolerate the voltage drop across the ESD protection
resistor on the analog_io[] pin.

Analog circuits that need 3.3V-5.0V compatible digital controls can
make use of the gpio_in_h digital inputs from the GPIO pins, which
are in the high voltage domain.  However, there is no equivalent
GPIO high voltage output, so any outputs in a high voltage domain
must be level-shifted to 1.8V before connecting to a gpio_out[] pin.

Caravel board compatibility:

To keep compatibility with the caravel circuit board, projects should
note which pins connect on the board to other (potentially) driving 
circuitry:  Pins gpio[1] through gpio[4] connect to the FTDI chip (used
by the housekeeping SPI on Caravel, and which can theoretically be
placed into a high-impedence state through software).  Pin gpio[38]
connects to the CMOS clock (which can be disabled to a high impedence
state with a jumper); pins gpio[39] to gpio[42] connect directly to
the SPI flash chip and can only be disconnected by desoldering the
SPI flash chip; and pin gpio[43] is connected to an LED.  Pins gpio[5]
and gpio[6] connect to switches which allow them to be connected to
the FTDI (UART function) but will normally be in a high-impedence
state.  All other GPIO pins connect only to header pins on the
development board.

Building
--------

For instructions on building (hardening) the OpenFrame Example project,
please refer to the [README](./README) containing the build notes.

This project example was built using locally installed tools and not
with docker.  Instructions are specific to my local build environment
but hopefully with enough commentary to be more generally useful.  It
should also be possible to build the project in the Efabless-recommended
docker environment.

Submitting
----------

(To be completed)

Contributing
------------

Bug fixes are always welcome.  Enhancements will be considered if they
demonstrate some useful technique that can only be achieved with the
Openframe version.  Otherwise, this project example is meant to be just
that---an example to learn from and build on for your own Openframe
project.  The best way to contribute is to create your own open source
Openframe project for a ChipIgnite shuttle run.

License
-------

The Caravel Openframe harness chip design on which this example depends
is distributed under the Apache-2.0 license.  This project example is
also distributed under the Apache-2.0 license (see the LICENSE file).