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

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

opencos/docs/eda.md

@@ -0,0 +1,147 @@
+# EDA Tool
+
+## Install
+
+Using `uv` (recommended):
+
+From PyPI:
+```
+uv tool install opencos-eda
+```
+
+OR, from the repo:
+```
+uv tool install /path/to/your/checkout/dir/of/opencos
+```
+
+This makes the `eda` and `oc_cli` commands available in your environment.
+
+## Basic Recipes
+
+Run a single simulation using the default simulator (of those installed).
+`oclib_fifo_test` is target in `./lib/tests/DEPS.yml`
+```
+eda sim lib/tests/oclib_fifo_test
+```
+
+Run the same single simulation, but use `verilator`, dump waves
+```
+eda sim --waves --tool verilator lib/tests/oclib_fifo_test
+```
+
+Run the same single simulation, but use `vivado` XSim, and run in GUI mode
+```
+eda sim --gui --tool vivado lib/tests/oclib_fifo_test
+```
+
+Run a compile + elab without a DEPS.yml file or target involved for dependencies
+```
+eda elab --tool verilator +incdir+. ./lib/oclib_assert_pkg.sv ./lib/oclib_simple_reset_sync.sv
+
+## Basic CLI usage:
+eda <command> [--args] [+incdir+DIR|+define+KEY=VALUE|+plusarg=value] file1.sv file2.sv file3.sv
+```
+
+## Example Regression testing
+
+```
+eda multi sim '.../*_test' --parallel 16
+eda multi elab 'lib/*' --parallel 16
+eda multi elab 'sim/*' --parallel 16
+eda multi elab 'top/*' --parallel 16
+```
+
+If you'd like output to stdout, which is how our github Actions are run, use `--verbose` with `eda multi`
+```
+eda multi sim --verbose lib/tests/oc*test
+```
+
+## Example "sweep"
+
+Sweeping a build across a range of parameters
+
+```
+eda sweep build u200 --seed=SEED "SEED=(1,2)" +define+OC_MEMORY_BIST_PORT_COUNT=PORTS "PORTS=[1,4,8,16,32]" +define+TARGET_PLL0_CLK_HZ=MHZ000000 "MHZ=(200,400,50)" --parallel 12
+```
+
+## Example for building treating non .sv file(s) as systemverilog
+
+```
+eda sim --tool verilator sv@several_modules.txt --top=my_module
+```
+
+Note that you can prefix source files with `sv@`, `v@`, `vhdl@` or `cpp@` if the file contents do not match their filename extension, and you would like `eda` to force use that file as, for example, systemverilog.
+
+
+# Help
+
+```
+eda help
+```
+
+```
+$ eda help
+INFO: [EDA] eda: version X.Y.Z
+INFO: [EDA] eda_config: --config-yml=eda_config_defaults.yml observed
+INFO: [EDA] eda_config: using config: ..../site-packages/opencos/eda_config_defaults.yml
+INFO: [EDA] *** OpenCOS EDA ***
+INFO: [EDA] Detected slang (/usr/local/bin/slang), auto-setting up tool slang
+INFO: [EDA] Detected verilator (/usr/local/bin/verilator), auto-setting up tool verilator
+INFO: [EDA] Detected surelog (/usr/local/bin/surelog), auto-setting up tool surelog
+INFO: [EDA] Detected gtkwave (/usr/bin/gtkwave), auto-setting up tool gtkwave
+INFO: [EDA] Detected vivado (/tools/Xilinx/Vivado/VVVV.v/bin/vivado), auto-setting up tool vivado
+INFO: [EDA] Detected slang_yosys (/usr/local/bin/yosys), auto-setting up tool slang_yosys
+INFO: [EDA] Detected iverilog (/usr/local/bin/iverilog), auto-setting up tool iverilog
+
+Usage:
+    eda [<options>] <command> [options] <files|targets, ...>
+
+Where <command> is one of:
+
+    sim          - Simulates a DEPS target
+    elab         - Elaborates a DEPS target (sort of sim based LINT)
+    synth        - Synthesizes a DEPS target
+    flist        - Create dependency from a DEPS target
+    proj         - Create a project from a DEPS target for GUI sim/waves/debug
+    multi        - Run multiple DEPS targets, serially or in parallel
+    tools-multi  - Same as 'multi' but run on all available tools, or specfied using --tools
+    sweep        - Sweep one or more arguments across a range, serially or in parallel
+    build        - Build for a board, creating a project and running build flow
+    waves        - Opens waveform from prior simulation
+    upload       - Uploads a finished design into hardware
+    open         - Opens a project
+    export       - Export files related to a target, tool independent
+    help         - This help (without args), or i.e. "eda help sim" for specific help
+
+And <files|targets, ...> is one or more source file or DEPS markup file target,
+    such as .v, .sv, .vhd[l], .cpp files, or a target key in a DEPS.[yml|yaml|toml|json].
+    Note that you can prefix source files with `sv@`, `v@`, `vhdl@` or `cpp@` to
+    force use that file as systemverilog, verilog, vhdl, or C++, respectively.
+
+
+opencos common options:
+  --version
+  --color, --no-color   Use shell colors for info/warning/error messaging (default: True)
+  --quiet, --no-quiet   Do not display info messaging
+  --verbose, --no-verbose
+                        Display additional messaging level 2 or higher
+  --fancy, --no-fancy
+  --debug, --no-debug   Display additional debug messaging level 1 or higher
+  --debug-level DEBUG_LEVEL
+                        Set debug level messaging (default: 0)
+  --logfile LOGFILE     Write eda messaging to logfile (default disabled)
+  --force-logfile FORCE_LOGFILE
+                        Set to force overwrite the logfile
+  --no-respawn          Legacy mode (default respawn disabled) for respawning eda.py using $OC_ROOT/bin
+
+opencos eda config options:
+  --config-yml CONFIG_YML
+                        YAML filename to use for configuration (default eda_config_defaults.yml)
+
+eda options:
+  -q, --quit   For interactive mode (eda called with no options, command, or targets)
+  --exit       same as --quit
+  -h, --help
+  --tool TOOL  Tool to use for this command, such as: modelsim_ase, verilator, modelsim_ase=/path/to/bin/vsim, verilator=/path/to/bin/verilator
+  --eda-safe   disable all DEPS file deps shell commands, overrides values from --config-yml
+```

opencos/docs/oc_cli.md

@@ -0,0 +1,135 @@
+
+USAGE
+=====
+
+[sudo] oc_cli --serial <port>
+
+<port> can be COM<x> (Windows) or /dev/ttyUSB<x> (Linux).  Depending on permissions for /dev/ttyUSB<x>, sudo maybe required.
+
+<port> can also be "tcp:<ip>:<port>:<device>" for connecting via TCP-to-UART bridge.
+
+GLOBAL COMMANDS
+===============
+
+info
+^^ prints compile-time info (UUID, build time/date, included userspace, etc)
+
+scan
+^^ scans the top level (ring) interfaces and reports the type of IP on each channel
+
+perf (NOT PORTED YET)
+^^ does a performance test of the comms channel
+
+debug <n>
+^^ set debug level <n>.  without argument, reports debug level.
+
+ping
+^^ sends <CR> and checks for a prompt, sends "^" and checks for a syntax error response.
+
+reset
+^^ sends 64x '!' characters, which initiates a full chip reset regardless of the state of the device.
+
+source <script file>
+^^ reads in a script with oc_cli commands
+
+import <python file>
+^^ reads in Python code to extend the commands oc_cli understands.  Typically used to pull in a userspace "driver".  Can also be used to "live patch" oc_cli during development work.
+
+set <var> <value>
+^^ sets a variable for use in oc_cli commands.  Refer to variables with $<var> syntax.  Typically used to enable scripts (see 'source') that are independent of channel allocation in the target (for example, 'set user_ch 4' and then a script doing 'memtest $user_ch xxx')
+
+read|rd|r <address> [<channel> <address space>]
+^^ reads a CSR in the device.  <channel> and <address space> are optional after the first rd/wr command; if not provided, the prior values will be used.
+
+write|wr|w <address> <data> [<channel> <address space>]
+^^ writes a CSR in the device.  <channel> and <address space> are optional after the first rd/wr command; if not provided, the prior values will be used.
+
+quit|q
+^^ exit oc_cli
+
+PLL COMMANDS
+============
+
+PLL commands are valid for channels that have a PLL IP (use 'scan' if not sure)
+
+pll <channel>
+^^ dumps the state of the PLL
+
+pll <channel> measure
+^^ measure clock 0 (for now) of the PLL on <channel>
+
+pll <channel> reset
+^^ reset PLL on <channel>.  Generally required after changing multipliers, dividers, etc.
+
+pll <channel> all_up (or all_down)
+^^ move all clocks on PLL up (or down) in frequency, by changing the feedback divider.  does not bounds check.
+
+pll <channel> clk0_up (or clk0_down)
+^^ move CLK0 on PLL up (or down) in frequency, by changing the fractional divider.  does not bounds check.
+
+pll <channel> throttle <level>
+^^ throttles the output clock 0 (for now).  <level> is 0-8, in 12.5% steps, with 0 meaning "no throttling" and 8 meaning "complete stop".
+
+pll <channel> freq <mhz>
+^^ attempts to set the clock of PLL <channel> to <mhz>.  NOT IMPLEMENTED YET!!!  (it's non-trivial)
+
+pll <channel> ramp <command list>
+^^ runs <command list> (an arbitrary oc_cli command line) at the current clock speeds, then ramps up the speed by reducing the fractional divider on the clock.  This will test some limited range (for example 350-410MHz).  To go beyond this, manually changing VCO freq, dividers, etc, will be required.
+
+
+CHIPMON COMMANDS
+================
+
+CHIPMON commands are valid for channels that have a CHIPMON IP (use 'scan' if not sure)
+
+chipmon <channel>
+^^ dumps the state of the CHIPMON
+
+
+PROTECT COMMANDS
+================
+
+PROTECT commands are valid for channels that have a PROTECT IP (use 'scan' if not sure)
+
+protect <channel>
+^^ dumps the state of the PROTECT, including the bitstream ID and the FPGA's unique DNA fingerprint (both of which usually required to get a license)
+
+protect <channel> unlock <key>
+^^ unlocks the bitstream protection using <key>
+
+MEMTEST COMMANDS
+================
+
+MEMTEST is available in the default userspace, and will not be in other userspaces unless specifically included (in which case, there maybe other commands needed to configure the userspace to connect memtest to the memory channels being tested).
+
+memtest <channel>
+^^ dumps the state of the MEMTEST
+
+memtest <channel> <args>
+^^ <args> is:
+   write               - enables writing memory
+   read                - enables reading memory
+   verbose=<x>         - set verbosity to <n> (default 1)
+   ops=<x>             - run <x> operations per port under test (default 1)
+   addr=<x>            - <x> is the base address in memory (default 0)
+   addr_incr=<x>       - <x> as the amount to increment per op (default 0x20, 32 Bytes)
+   addr_incr_mask=<x>  - <x> is a bitmask applied to the increment value before ORing with addr (default 0xffffffffffffffff)
+   addr_rand_mask=<x>  - <x> is a bitmask applied to a random value before ORing with addr (default 0)
+   addr_port_shift=<x> - <x> is the amount to shift the port number to the left before ORing with addr (default 0)
+   addr_port_mask=<x>  - <x> is a bitmask applied to the shifted port number before ORing with addr (default 0)
+   waits=<x>           - <x> is the number of waitstates between ops (default 0)
+   burst=<x>           - <x> is the number of words in each op (default 1).  Note the CSR actually will hold (burst-1).
+   pattern=<x>         - <x> is a 32-bit seed for pattern generation (used to generate write data) (default 0x11111111).
+   signature=<x>       - <x> is the expected signature (which is a combination of all read data)
+   write_max_id        - <x> is the highest AXI ID used for issuing writes (default 0)
+   read_max_id         - <x> is the highest AXI ID used for issuing reads (default 0)
+   prescale            - sets the counter prescaler, will divide counters by N so that they can be sampled at the end of long tests
+   write_len_rand      - enables random write length
+   read_len_rand       - enables random read length
+   write_data_rotate   - enables write data rotation, ensures bus toggling without random data (which can be harder to make sense of in waves)
+   write_data_random   - enables write data randomization (still 'pseudorandom' and will be repeatable in terms of read signature)
+   measure             - report AXI-Lite and AXI3 clock speeds, cycles under reset, and cycles since reset
+   nopoll              - kick off the MEMTEST engine, but don't wait for completion, so oc_cli can be used to monitor temps, etc
+   stats               - report stats (latency, contexts) in summary, or per-port (verbose>1)
+   get_sigs            - report per-port signatures
+   signature_<p>=<x>   - set port <p> expected signature to <x> (default for all ports is -1, which means don't check)