opencos-eda 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

opencos/docs/Architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+Looking at it roughly bottom up.
+
+## oc_user.sv
+
+A "userspace" app is loaded, via pointing a build to a DEPS target that pulls in an oc_user.sv.
+
+There is an associated oc_user.vh which contains:
+- `defines which configure the internals of the user-space app, and can be whatever is required by the application. They don't need OC_* prefixes, etc
+- `defines which configure the interface to the operating system, and are defined by OpenCOS.  These OC_USER_* defines configure the ports of oc_user and it's instantiation in oc_cos.
+
+Userspace apps which "ship" with OpenCOS are in the <oc>/user directory, but they can be located anywhere (TBD: document how that is done)
+
+TODO: define a userspace testbench.  The OC_COS and above levels are implemented behaviorally for flexible testing at the userspace API level.
+
+## oc_cos.sv
+
+The "operating system", which instantiates the userspace app, as well as a collection of top level modules.  It is stores in <oc>/top
+
+oc_cos configures itself via two sets of defines:
+- OC_COS_* defines which enable services from the operating system.  For example the userspace could request that ethernet bridging is enabled between 4 external and 4 userspace ports, instead of direct connection.  The board may setup features such as fan and LED controls.  Meanwhile the integrator may enable things like bitstream licensing.
+- OC_BOARD_* defines which are set by the board target DEPS, and configure the ports of oc_cos.  The goal is for OC_BOARD defines to setup the defaults for the parameters of oc_cos, not for them to be used repeatedly internally.  Some things cannot be done that way (for example setting module names).
+
+Testing is performed via <oc>/top/tests/oc_cos_*test targets, which should aim to instantiate as much as possible, while testing the subset that the testbench knows how to test.  Practically speaking, the kinds of tests run at this level should consider not duplicating the tests that operate at the next stage up (board level).
+
+TODO: do we require board target to use DEPS?  what if they just want to have defines in a file, how do we ensure it's read before oc_cos (we could add a way for oc_cos to pull in a header file)
+
+## oc_chip_top.sv
+
+This is the typical (but not mandatory) name of the top level for a given target.  This is stored in a <oc>/boards/<board> directory.
+
+The concept of oc_chip_top is like a "board support package" for an operating system, the thin shim that connects the shared code with the unique target.  It likely instantiates I/O buffers, maybe connects some pins that are unique to the board (things to do with bringup sequence, custom thermal solutions, etc).  Basically, anything that OC_COS cannot handle, needs to be put up here.
+
+It's entirely optional for oc_chip_top to configure oc_cos via parameter.  oc_cos will setup it's ports based on OC_BOARD defines, and overriding the parameters so they don't match the defaults could result in inconsistent state if the design looks at the OC_BOARD defines again.  oc_chip_top
+
+TODO: work on the naming.  it's called a target, a board, oc_chip_top, etc, and it's confusing.
+
+## oc_chip_harness.sv
+
+The purpose of oc_chip_harness is to "reverse" the transformation between oc_cos ports (ledOut[1:0], pciRxP[15:0], etc) and oc_chip_top ports (LED_GREEN, LED_RED, PCI_RXP_15, PCI_RXP_14, etc).  It terminates any custom interface coming out of oc_chip_top in a way that makes sense.  Upwards, it shows ports that look like oc_cos.  In this way, oc_cos tests (including those that test userspace apps) can be run on oc_chip_top (i.e. including all board customizations).
+
+The upward facing ports need to match the upward facing oc_cos ports.  This can be done "with care", or can be done by examining OC_BOARD_* defines and setting up params and ports to match.
+
+oc_chip_harness does not accept params, and oc_cos_test runs in a mode where it doesn't push params.  Instead it is expected that OC_BOARD_* defines from the board DEPS will configure oc_cos (definitely) and oc_chip_top/oc_chip_harness (optionally).

opencos/docs/ConnectingApps.md

@@ -0,0 +1,29 @@
+# Connecting Apps
+
+The API between oc_top and oc_user is perhaps the area where OpenCOS diverges the most from the OS/Userspace parallel in the software world. 
+
+Similarities:
+- In both cases, we desire to give a stable API to our userspace apps.  Existing APIs should not change.
+- As new APIs are made available, they shouldn't break existing applications.
+Differences:
+- The OS can add new APIs and expose them to userspace, without significant cost, and without changes to userspace.  In hardware, connectivity between OS and userspace is in the form of physical wires that must be connected.
+
+Furthermore, module ports (and connections to instance ports) cannot be made dependent on parameters.  Either all ports are always there, or they must be made conditional on `defines.  
+
+We desire to not burden userspace with unnecessary complexity.  For example, if it does not require networking, it shouldn't have to declare network ports. 
+
+We desire that the userspace can be flexible.  For example, if it is a memory tester, it would be nice if it could scale the number, width, and type of interfaces (for example, connecting to four 512-bit AXI-3 interfaces, or thirty-two 256-bit AXI-4 interfaces).  
+
+We desire that the top level (`oc_top`) only contains logic required to meet user-space requests.  We don't "build everything in" and then just connect what we need. 
+
+The following methodology is used: 
+
+- Userspace declares via a header (`oc_user_defines.vh`) what types of interfaces it can connect to.
+    - This includes a class (local memory), an interface type (AXI-4), a width (512-bit), and a count (4)
+    - This file is not expected to be edited by the integrator.  But it may note defines that can be set in `oc_board_defines.vh` to configure functionality within the userspace app.  
+- The board comes with a header file that (`oc_board_defines.vh`) that the integrator edits to constrain which external interfaces are connected.  This file will also set the defines which activate `oc_top` ports connecting out to the chip interfaces.  It can also hint to `oc_top` about internal features to enable, when they can't be inferred just from the interfaces (for example, a define could enable Ethernet switching functionality between external network interfaces and userspace)
+- The board-specific `oc_chip_top` will take the `oc_board_defines.vh` and drive parameters into `oc_top`
+    - do we need this?
+- `oc_top` will read `oc_board_defines.vh` to enable ports out to chip interfaces. 
+- `oc_top` will read `oc_user_defines.vh` to know what interfaces must be connected to userspace.
+- `oc_top` will infer what internal functions are needed based on board and user defines.  

opencos/docs/DEPS.md

@@ -0,0 +1,199 @@
+# DEPS.yml schema:
+
+(Note this information, DEPS.md, is also available via: eda deps-help --verbose)
+
+```
+DEFAULTS: # <table> defaults applied to ALL targets in this file, local targets ** override ** the defaults.
+
+METADATA: # <table> unstructured data, any UPPERCASE first level key is not considered a target.
+
+target-spec:
+
+  args: # <array or | separated str>
+    - --waves
+    - --sim_plusargs="+info=500"
+
+  defines: # <table>
+    SOME_DEFINE: value
+    SOME_DEFINE_NO_VALUE:   # we just leave this blank, or use nil (yaml's None)
+
+  plusargs: # <table>
+    variable0: value
+    variable1:              # blank for no value, or use nil (yaml's None)
+
+  parameters: # <table>
+    SomeParameter: value
+    SOME_OTHER_PARAMETER: value
+
+  incdirs: # <array>
+    - some/relative/path
+
+  top: # <string>
+
+  deps: # <array or | space separated string>
+    - some_relative_target       # <string> aka, a target
+    - some_file.sv               # <string> aka, a file
+    - sv@some_file.txt           # <string> aka, ext@file where we'd like a file not ending in .sv to be
+                                 # treated as a .sv file for tools.
+                                 # Supported for sv@, v@, vhdl@, cpp@, sdc@, f@, py@, makefile@
+    - commands:                  # <table> with key 'commands' for a <array>:  support for built-in commands
+                                 # Note this cannot be confused for other targets or files.
+      - shell: # <string>
+        var-subst-args: # <bool> default false. If true, substitute vars in commands, such as {fpga}
+                        # substituted from eda arg --fpga=SomeFpga, such that {fpga} becomes SomeFpga
+        var-subst-os-env:  #<bool> default false. If true, substitute vars in commands using os.environ vars,
+                           # such as $FPGA could get substituted by env value for it.
+        tee: # <string> optional filename, otherwise shell commands write to {target-spec}__shell_0.log
+        run-from-work-dir: #<bool> default true. If false, runs from the directory of this DEPS file.
+        filepath-subst-target-dir: #<bool> default true. If false, disables shell file path
+	                           # substituion on this target's directory (this DEPS file dir).
+        dirpath-subst-target-dir: #<bool> default false. If true, enables shell directory path
+	                          # substituion on this target's directory (this DEPS file dir).
+        run-after-tool: # <bool> default false. Set to true to run after any EDA tools, or
+	                # any command handlers have completed.
+      - shell: echo "Hello World!"
+      - work-dir-add-sources: # <array or | space separated string>, this is how to add generated files
+                              # to compile order list.
+      - peakrdl:              # <string>     ## peakrdl command to generate CSRs
+
+  reqs: # <array or | space separated string>
+    - some_file.mem           # <string> aka, a non-source file required for this target.
+                              # This file is checked for existence prior to invoking the tool involved, for example,
+                              # in a simulation this would be done prior to a compile step.
+
+  multi:
+    ignore-this-target:  # <array of tables> eda commands to be ignored in `eda multi <command>` for this target only
+                         # this is checked in the matching multi targets list, and is not inherited through dependencies.
+      - commands: synth  # space separated strings
+        tools: vivado    # space separated strings
+
+      - commands: sim # omit tools, ignores 'sim' commands for all tools, for this target only, when this target
+                      # is in the target list called by `eda multi`.
+
+      - tools: vivado # omit commands, ignores all commands if tool is vivado, for this target only, when this target
+                      # is in the target list called by `eda multi`.
+
+    args: # <array> additional args added to all multi commands of this target.
+          # Note that all args are POSIX with dashes, --sim-plusargs=value, etc.
+
+  <eda-command>: # key is one of sim, flist, build, synth, etc.
+                 # can be used instead of 'tags' to support different args or deps.
+    args: # <array or | space separated string>
+    defines: ## <table>
+    plusargs: ## <table>
+    parameters: ## <table>
+    incdirs: ## <array>
+
+  tags: # <table> this is the currently support tags features in a target.
+    <tag-name>: # <string> key for table, can be anything, name is not used.
+      with-tools: <array or | space separated string>
+                  # If using one of these tools, apply these values.
+                  # entries can be in the form: vivado, or vivado:2024.1
+      with-commands: <array or | space separated string>
+                  # apply if this was the `eda` command, such as: sim
+      with-args: # <table> (optional) arg key/value pairs to match for this tag.
+                 # this would be an alternative to running eda with --tags=value
+                 # The existence of an argument with correct value would enable a tag.
+                 # And example would be:
+                 #   with-args:
+                 #     waves: true
+      args: <array or | space separated string> # args to be applied if this target is used, with a matching
+                                          # tool in 'with-tools'.
+      deps: <array or | space separated string, applied with tag>
+      defines: <table, applied with tag>
+      plusargs: <table, applied with tag>
+      parameters: <table, applied with tag>
+      incdirs: <array, applied with tag>
+      replace-config-tools: <table>  # spec matching eda_config_defaults.yml::tools.<tool> (replace merge strategy)
+      additive-config-tools: <table> # spec matching eda_config_defaults.yml::tools.<tool> (additive merge strategy)
+
+```
+
+## Examples
+
+### Target with tag-mode:
+
+```
+target-foo-with-tags:
+   deps: some_file1.sv some_file2.sv
+   tags:
+
+     # This can be invoked with eda --tool=vivado --gui
+     xilinx_mode:
+       with-args:
+         gui: true
+       with-tools: vivado
+       deps: <some_deps_for_this_fpga>
+       defines:
+         XILINX_GUI_MODE: 1
+
+     defaults:
+       deps: some_dummy_dep_not_fpga
+
+```
+
+
+### Simple Target, with deps as an explicit list
+
+This is the basic, common format for a target. target - deps - (array of files or other relative targets). The file order is compile order, top to bottom.
+
+```
+some-target:
+  deps:
+    - ../foo/some_prev_target
+    - some_other_target
+    - some_file.sv
+```
+
+### Simple Target, with deps as a string with \n separators
+
+This is more terse variant ` deps: |` followed by a string of targets and source files.
+
+```
+some-target2:
+  deps: |
+    ../bar/some_prev_target2
+    some_file2.sv
+    some_other_target2
+```
+
+### Simple Target, non-table (strings)
+
+The most terse variant for a target is a array or \n separated string, not a table, with no `deps` key, then it is assumed that all entries are other targets or sources.
+
+```
+some-target3: |
+  ../bar/some_prev_target3
+  some_file3.sv
+  some_other_target3
+```
+
+You could also explicitly make a list without a `deps` key:
+```
+## target entry is an explicit list
+some-target4:
+  - ../bar/some_prev_target4
+  - some_file4.sv
+  - some_other_target4
+```
+
+You can also have space separated in a string:
+```
+some-target5: ../bar/some_prev_target5  some_file5.sv
+```
+
+### Defines with relative path
+
+Defines with file path information relative to a DEPS.yml file are supported with special words `%PWD%` as a replacement for ./ in defines only. This is necessary because we do not do path substituion on defines.
+
+Example:
+
+```
+my_define_target:
+  deps:
+    - my_dut.sv
+    - my_testbench.sv
+  defines:
+    SOME_FILE: >
+      "%PWD%/my_pcap.pcap"
+```

opencos/docs/Debug.md

@@ -0,0 +1,77 @@
+
+
+CogniX has a few things that should help debug.
+
+1) Direct connection to COS control layer.  This is like "root" on Linux, being able to direct access the I/O (read buttons, override LEDs, fans, PLLs...).  Via this path, we can also fake the user interactions (emulate a button press, see what userspace is driving to LEDs, etc), which is great for testing the user space itself.  It's also useful for outward facing debug, i.e. ensuring COS is properly connected to the board (without needing userspace at all). 
+
+2) Debug Macros:  Virtual Input/Output, Integrated Logic Analyzer, etc. 
+
+* Virtual Input/Output will be mapped to the appropriate target-specific feature, generally a GUI connecting to the target via JTAG.  
+
+Remind the user that generally this requires an IP to be built for the appropriate parameter sizes.  The board/vendor will have certain sizes prebuilt.  
+
+  32 inputs,   32 outputs : the only size required to be universally supported (CogniX itself uses this). 
+
+# ─── Example: Virtual Input/Output
+
+logic [27:0] clockSignalDivide;
+always_ff @(posedge clockSignal) clockSignalDivide <= (clockSignalDivide+1);
+
+`OC_DEBUG_VIO(uMY_VIO, clockSignal, 32, 32,            // 32 inputs, 32 outputs respectively
+   { clockSignalDivide[27], resetSignal, chipStatus }, // signals to monitor, and send to the GUI in realtime
+   { resetFromVio, enableFromVio } );                  // signals to receive from the GUI in realtime
+
+# ───
+
+* Integrated Logic Analyzer will be mapped to the appropriate target-specific feature, generally a GUI connecting to the target via JTAG.  
+
+Remind the user that generally this requires an IP to be built for the appropriate parameter sizes.  The board/vendor will have certain sizes prebuilt.  
+
+An ILA is triggered by something (including a manual button press on the GUI) and then captures all incoming cycles for "Depth" clock cycles.  They can be configured to trigger on events that appear on their inputs (typically reset, valid, busy, error, transaction type, etc.)  Usually only a subset of signals have this trigger ability, since it is far more complex to examine the inputs vs just record them.  
+
+Note that not all sizes are built by default, just common ones.  Enabling less common debug may require ILA IPs to be uncommented in the build.tcl. 
+
+  1024 deep, 128 data,   32 trigger : the most common size. 
+  1024 deep, 512 data,   32 trigger : for when 512 bit data is needed (high bandwidth interfaces). 
+  8192 deep,   8 data,    8 trigger : deep and narrow (byte-oriented interfaces, like BC CSR). 
+  8192 deep, 128 data,   32 trigger : a deeper version of the most common size (prob second most common)
+131072 deep,   8 data,    8 trigger : long traces (IIC, etc) 
+
+# ─── Example: Integrated Logic Analyzer
+
+logic [7:0] clockSignalDivide;
+always_ff @(posedge clockSignal) clockSignalDivide <= (clockSignalDivide+1);
+
+`OC_DEBUG_ILA(uMY_ILA, clockSignal, 8192, 128, 32,      // 8192 deep, 128 data inputs, 32 trigger inputs
+   { clockSignalDivide[7:0], dataBus[31:0] },           // signals fed into the capture buffer
+   { resetSignal, chipStatus } );                       // signals fed into the capture buffer AND trigger logic
+
+# ───
+
+3) Built-In DEBUG
+
+The following built-in debug can be enabled by settings these defines in DEPS or command-line
+
+* OC_COS_BC_MUX_DEBUG                   : Adds ILA to the logic that muxes command streams from UART, PCIe, and JTAG sources
+* OC_COS_GPIO_DEBUG                     : Adds ILA to buttons, toggles, leds, rgbs, gpio, fan, chipStatus, and reset. 
+* OC_COS_CSR_TREE_DEBUG                 : Adds ILA into the uTOP_CSR_SPLITTER, to debug CSR connectivity between
+
+These defines enable built-in debug into the modules of associated name (i.e. to debug "oc_pcie", use OC_PCIE_DEBUG)
+
+* OC_PCIE_DEBUG
+* OC_HDMI_IN_DEBUG
+* OC_CHIPMON_DEBUG
+* OC_PROTECT_DEBUG
+* OC_IIC_DEBUG
+* OC_BC_CONTROL_DEBUG
+* OC_AXIL_CONTROL_DEBUG
+* OC_UART_CONTROL_DEBUG
+* OCLIB_MEMORY_BIST_DEBUG
+* OCLIB_READY_VALID_ROM_DRIVER_DEBUG
+
+The modules have an EnableILA parameter which can be manually enabled on a given instance (enabling them globally is too expensive)
+
+* oclib_csr_adapter
+* oclib_csr_tree_splitter
+
+

opencos/docs/DirectoryStructure.md

@@ -0,0 +1,22 @@
+# Directory Structure
+
+`boards`
+- A set of target boards, platforms, etc
+  
+`apps`
+- A set of applications that can be loaded
+
+`top`
+- Files implementing the top-level (aka "operating system")
+
+`sim`
+- Simulation related transactors.  These are used in tests, and are kept separely `top` and `lib` because they aren't expected to be compiled/elaborated in isolation.  
+
+`lib`
+- Files implementing the OpenCOS standard library
+
+`bin`
+- Scripts, binaries, programs
+
+`docs`
+- OpenCOS documentation area

opencos/docs/Installation.md

@@ -0,0 +1,117 @@
+# Installation
+
+## Prerequisites
+
+- Linux or Windows+WSL.
+- bash
+- python3.8 or newer
+- At least one simulator or synthesis tool
+  - *[Verilator](https://verilator.org/guide/latest/)*
+  - *[Xilinx Vivado](https://www.xilinx.com/support/download.html)*
+      - [Alternate link amd.com](https://docs.amd.com/r/en-US/ug973-vivado-release-notes-install-license/Download-and-Installation)
+  - *[Modelsim ASE](https://www.intel.com/content/www/us/en/software-kit/750666/modelsim-intel-fpgas-standard-edition-software-version-20-1-1.html)*
+
+## Installation
+
+
+Easiest is to install the package as a tool, which makes `eda` and `oc_cli` available in your environment:
+
+Before starting, make sure `uv` is installed per the [instructions](https://docs.astral.sh/uv/getting-started/installation/):
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### PyPi
+
+Install directly from PyPi:
+```
+uv tool install opencos-eda
+```
+
+If you intend to use cocotb with `eda`, you will need an optional dependency:
+```
+uv tool install opencos-eda[cocotb]
+```
+
+### Github repo
+
+Alternately, you can install the package from the Github repo:
+
+Clone this repo:
+```
+gh repo clone cognichip/opencos
+
+# OR
+
+git clone https://github.com/cognichip/opencos.git
+```
+
+Install the local package:
+```
+uv tool install /path/to/your/checkout/dir/of/opencos
+
+# Or:
+uv tool install /path/to/your/checkout/dir/of/opencos[cocotb]
+```
+
+### Verify installation
+
+Check that `eda` is in your $PATH
+```
+which eda
+```
+
+
+## Developing
+
+You may want to install the dev dependencies into the virtual environment:
+(Note that cocotb is an optional dependency)
+```
+uv sync --locked --extra dev --extra cocotb
+```
+
+Run the tools by first activating the environment:
+```
+source .venv/bin/activate
+eda
+```
+
+You can confirm which instance is being used:
+```
+which eda
+```
+
+Or let `uv` deal with the virtual environment management, which also guarantees you're running the local development version:
+```
+uv run eda
+```
+
+For developers checking cocotb related tests (via pytests, or running eda targets in examples/cocotb) you will need to make sure `find_libpython` returns a .so file. This is most easily fixed with:
+```
+uv python install 3.12
+```
+3.12, or a different version, based on the pinned version if present in root .python-version, or the python version you wish to test. `find_libpython` may have issues if your python installation was performed outside of `uv` (such as, an ubuntu22 install of python3.12 via ppa:deadsnakes/ppa).
+
+
+## Recommended:
+
+Xilinx Vivado suite
+
+- NOTE: licenses are not required to build designs for certain targets (generally Alveo boards: U200, U50, etc).  Other Xilinx kits contain licenses supporting the device used in the kit (Kintex 7, etc).  For other situations, a license is required to build bitfiles.  Certain IPs (Xilinx 25GMAC for example) may require additional licenses – we are always looking for open source versions of such IP :)
+- `https://www.xilinx.com/support/download.html`
+- Minicom (or another serial terminal)
+- For debugging.  `oc_cli` should be all that is needed, but at some point many folks will need a vanilla serial terminal.
+
+
+## Installation Known issues
+
+If you encounter issues with `uv sync`, ensure that `uv` is up to date:
+
+```
+uv --version
+
+# Update uv if needed
+uv self update
+```
+
+If you encounter issues with the version of Python, note that `uv` respects the `.python_version` (if present) and `requires-python` in `pyproject.toml`. See [docs](https://docs.astral.sh/uv/concepts/python-versions/).

opencos/docs/OcVivadoTcl.md

@@ -0,0 +1,63 @@
+# oc_vivado.tcl
+
+Path: `<oc_root>/boards/vendors/xilinx/oc_vivado.tcl`
+
+This TCL file provides many services for OpenCOS in the Xilinx Vivado tool. 
+
+## Contexts 
+
+The `oc_vivado.tcl` file is designed to be sourced in a variety of contexts,  adapting what actions it takes depending on context.  The supported contexts are:
+
+- Sourced into a new instance of Vivado, before a project is opened.  This may occur because it was sourced via command line, or via `Vivado_init.tcl` file in the Vivado install.  Doing so enables the `oc_vivado.tcl` to assist opening the project, etc, but is generally not required.  When sourced this way, much of the setup cannot be done during sourcing (for example, setting `oc_projdir`, `oc_projname`).  Therefore, the `open_project` TCL proc is hooked, such that `oc_vivado.tcl` is sourced again automatically when a project is opened.
+- Sourced after a project is created/opened.  This may be done via the  `open_project` TCL hook, or via TCL console, or via TCL script being run to create the project.  In this context, the `launch_runs` and similar commands are hooked, to provide updated build timestamps, etc. 
+- Sourced as a constraint file during synthesis/implementation.  This this case the TCL is added into the constraint fileset.  Since each run launches a separate Vivado subprocess, `oc_vivado.tcl` must be resourced into those new processes.  This is important for automatic constraints, updating build timestamps, etc.  
+
+## Throwing Warnings
+
+See TCL proc `oc_throw_warning`
+
+When TCL runs into errors, it can either crash the whole process, or send the output to STDOUT.  The latter is almost guaranteed to be missed, given the typical quantity of output.  Vivado collects it's own Info, Warning, Errors into the GUI. 
+
+OpenCOS takes a hacky but effective approach, of attempting to access a non-existent pin (which throws a warning into the Vivado log).  The pin named such that the reason for the notification is clear (i.e. it may indicate a missing clock definition and give the clock name:  via searching for pin `OC_ADD_CLOCK_WARNING_clockTest_DOESNT_EXIST`)
+
+## Constraints
+
+See TCL procs starting with `oc_add_clock`
+
+There are three basic types of constraint assistence: 
+
+- Easing declaration (like `oc_add_clock`) by finding pins, failing safely where possible, etc. 
+- Automatic constraint inclusion (like `oc_auto_scoped_xdc` ) which search the design for _modules_ and pull in matching scoped XDC files
+- Automatic constraint inclusion (like `oc_auto_max_delay` ) which search the design for _attributes_ and infer constraints.  This is the preferred method of constraining, and used especially in clock-crossing libraries (`oclib_synchronizer`, etc)
+
+## Design Exploration
+
+See TCL procs starting with `oc_get_instances`
+
+Various TCL procs for finding instances, net drivers, load pins, etc. 
+
+## Define Manipulation
+
+See TCL procs starting with `oc_set_define_in_string`
+
+Various TCL procs for manipulating "define strings" that contain defines (adding defines, removing defines, overwriting existing define with same name, etc). 
+
+Also tasks to load define strings from the project, and save them back to the project.  These tasks will handle setting the define in one or more file sets, etc. 
+
+## Vivado Hooks
+
+See TCL procs starting with `oc_hook_*`
+
+If Vivado is opened 
+
+## Multirun
+
+See TCL procs starting with `oc_multirun_*`
+
+Various TCL functions that can be called from the TCL console in Vivado to create many implementations (different seeds, synth and implementation strategies, etc).
+
+Philosophically what this is doing is Vivado's "project mode" to leverage Vivado's ability to schedule jobs, run remote jobs, cache prior results, etc.  
+
+For "production" usage of multirun, it's best to create a local TCL file `multirun.tcl` that is sourced from Vivado TCL console, and which captures the multirun config (strategy, number of seeds, etc). 
+
+A more "hands-on" approach would be to call the underlying TCL functions (place_design, route_design, etc) potentially with multiple Vivado sessions for parallelism.  The lower level flow provides more control but there is a significant amount of complexity that Vivado hides (esp in the areas of IP and simulation models).  Eventually OpenCOS will have boards that are build using this lower level flow.  

opencos/docs/OpenQuestions.md

@@ -0,0 +1,7 @@
+# Open Questions
+
+## RTL Coding
+
+* Can we make tools behave well with a rational policy for unconnected ports?
+    * Unconnected outputs should be ignored (ideally we can flag an output as being "not ignorable" but that seems pretty vague).  It's not great that adding an output to a module causes warnings in previous usage that doesn't need the new feature
+    * Unconnected inputs should be ignored IF THEY HAVE A DEFAULT VALUE.  We get to set default values for inputs, why should we force people to tie them?

opencos/docs/README.md

@@ -0,0 +1,13 @@
+# OpenCOS Documentation
+
+## Chapters
+
+* [Installation](Installation.md)
+* [Directory Structure](DirectoryStructure.md)
+* [RTL Coding](RtlCodingStyle.md)
+* [DEPS.yml](DEPS.md)
+* [eda usage](eda.md)
+* [Connecting Apps](ConnectingApps.md)
+* [oc_vivado.tcl](OcVivadoTcl.md)
+* [Open Questions](OpenQuestions.md)
+* [Format Examples](format_examples/readme.md)

opencos/docs/RtlCodingStyle.md

@@ -0,0 +1,54 @@
+# RTL Coding
+
+## Organization
+
+### lib/oclib_*
+
+Library elements
+
+## Naming Style
+
+### Modules
+- lowercase_underlined
+- OC reserved prefixes: `oclib_*`, `oc_*`
+- Complete words: `oclib_synchronizer`
+    - Except for standard cases (`oclib_fifo`, `oclib_csr_to_drp`)
+
+### Parameters
+- CamelCase
+- Full words
+  
+### Ports/Signals
+- lowercase_underlined
+- Clocks must start with `clock`
+    - Various backend flows may rely on this
+    - Single clock modules should just have `clock`
+    - Multi-clock modules can use the default `clock` and others (`clockJtag`), or just several non-default clocks (`clockRead`, `clockWrite`)
+- Resets should start with `reset`
+    - When >1 reset, labels match clock (`clockAxi`/`resetAxi`)
+ 
+### Indentation
+- Matches Verilog-Mode for Emacs
+
+## Defines
+- Universal defines: `SIMULATION`, `SYNTHESIS`, `SEED`
+- OC reserved prefix: `OC_*`
+- Tool and version: `OC_TOOL_*`
+    - `OC_TOOL_VIVADO`, `OC_TOOL_VIVADO_2022.2`
+- Library: `OC_LIBRARY_*`
+    - `OC_LIBRARY_ULTRASCALE_PLUS`
+- Target: `OC_TARGET_*`
+    - `OC_TARGET_U200`
+  
+## Includes
+- Default settings by EDA
+    - `+incdir+<Root of OpenCOS repo>`
+    - `+libext+.sv+.v`
+- Include files should use header guards
+    - ``ifdef __LIB_OCLIB_DEFINES_VH`
+- RTL files should ``include` their dependencies (not include them in DEPS)
+
+## Parameters
+- Always have default values
+    - they may be invalid and caught with a static assert
+    - purpose here is to ensure modules can report detailed error ("You must set parameter X because ...") instead of not compiling