{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "49e84f0f-9795-448d-b968-4a618227bf2a",
   "metadata": {},
   "source": [
    "# Cyrite HDL documentation\n",
    "\n",
    "\n",
    "Overview:\n",
    "\n",
    "* [What is Cyrite HDL?](#What-is-Cyrite?)\n",
    "* [Introduction](howto/index.ipynb) : How to design hardware in Python\n",
    "* [API reference](howto/index.ipynb#The-Cyrite-API-reference)\n",
    "* [Extensions: Writing IRL classes](howto/extensions.ipynb)\n",
    "* [Examples](examples/index.ipynb)\n",
    "   * Procedural generation (Gray counters et al)\n",
    "   * Library extensions using 'intermediate language' constructs\n",
    "* [Notes for migration of MyHDL code](howto/migration/myhdl_migration.ipynb)\n",
    "* [Auto-Testing the notebooks](autotesting.ipynb): Making sure documentation is up to date\n",
    "\n",
    "\n",
    "## What is Cyrite?\n",
    "Cyrite was previously conceived as a number of hacks and experiments to procedurally generate pipelines  under the name *pyrite*, however, since considered 'taken' by another package, it was renamed cyrite.\n",
    "The underlying, newer IRL kernel (Intermediate Representation Layer  alias `myirl`) is partially written in Cython - compiled Python.\n",
    "\n",
    "The `myirl` kernel and library provides functionality to:\n",
    "\n",
    "* create VHDL or Verilog hierarchical code from a functional hardware description in Python\n",
    "* directly synthesize to RTLIL logic elements via yosys\n",
    "* drive simulation backends (iverilog, GHDL, CXXRTL, ...) for verification\n",
    "* emulate MyHDL syntax to some extent - with major differences:\n",
    "  * Strict typing and modular I/O\n",
    "  * Expressions are mostly generators\n",
    "* construction of high level synthesis pipelines and custom extensions\n",
    "* compile python HDL into binaries for performance and non-opensource purposes\n",
    "\n",
    "The myHDL-alike HDL entry level runs generally as 'cyrite HDL', whereas this is rather a library set than a real HDL.\n",
    "\n",
    "The internal IRL dialect again is meant for extensions. It is entirely generator based, as opposed to translation to target languages via AST.\n",
    "\n",
    "Its main goal is, to separate a functional description as far as possible from an inference rule, i.e. a specification of what to create from it. It is therefore context sensitive, either in an explicit way by a decorator, or a dynamic, implicit way according to an architecture specification."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b87be4cc-4fef-4e09-8eb1-d1509d1ed9fd",
   "metadata": {},
   "source": [
    "What it missing:\n",
    "* Native Python Simulator (yet)\n",
    "* A ready-made HLS tool (you need to define your own generator framework)\n",
    "* A drop-in replacement emulation for myHDL (not intended)\n",
    "* A full coverage verification of the entire library against all targets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9108c669-d371-44c6-b866-81f6caca54cb",
   "metadata": {},
   "source": [
    "## FAQs\n",
    "\n",
    "* Is VHDL-2019 support planned?\n",
    "\n",
    "  Not for the time being. It is unlikely that any FPGA toolchain on the market will implement the full VHDL-2019 support.\n",
    "  \n",
    "* Is this a myHDL fork?\n",
    "\n",
    "  No. It is a different kernel, originally designed to *procedurally generate* HDL/RTL pipelines.\n",
    "  It was partially rewritten to be compatible with other data types, such as myHDL's `intbv` which may still serve as 'state of the art' reference implementation for bit vectors.\n",
    "  \n",
    "* Is functionality being back-ported into MyHDL/a fork?\n",
    "\n",
    "  No, see above. The different kernel architecture doesn't allow that.\n",
    "  \n",
    "* Where is the github repository for the kernel?\n",
    "\n",
    "  There is none. The myIRL binary part of the kernel still contains proprietary code which is hosted in a private repository.\n",
    "  The cleanups for full opensource compatibility will come last.\n",
    "  \n",
    "* What is going to happen to myHDL direct synthesis via yosys ('jupyosys')?\n",
    "\n",
    "  The myHDL branch is left fully unmaintained and remains as possibly dysfunctional prototype. All further development is based on the cyrite ecosystem.\n",
    "\n",
    "* What's again gone wrong with MyHDL?\n",
    "\n",
    "  The main reasons are based on its architecture:\n",
    "  * Direct translation to the target HDL using AST was a path introducing much maintenance overhead (lifted by the IR layer)\n",
    "  * Not possible to compile HDL sources to binaries\n",
    "  * Lacking support for hierarchies and strict interfaces, in particular blackbox support for external modules\n",
    "  * Some name space irregularities and unsolved arithmetic bugs\n",
    "  * Performance issues for large projects using procedurally generated logic"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}