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).