docs: Adding "Known Issues" and "Versioning" sections of the documentation.

Extracted the status page into a separate file which can be included by
both the known issues and README files.

Signed-off-by: Tim 'mithro' Ansell <tansell@google.com>

README.rst

@@ -7,19 +7,22 @@ SkyWater Open Source PDK
    :alt: GitHub license - Apache 2.0
    :target: https://github.com/google/skywater-pdk
 
+.. image:: https://travis-ci.org/google/skywater-pdk.svg?branch=master
+   :alt: Travis Badge - https://travis-ci.org/google/skywater-pdk
+   :target: https://travis-ci.org/google/skywater-pdk
+
 .. image:: https://readthedocs.org/projects/pip/badge/?version=latest&style=flat
    :alt: ReadTheDocs Badge - https://skywater-pdk.rtfd.io
    :target: https://skywater-pdk.rtfd.io
 
 .. image:: https://img.shields.io/github/v/tag/google/skywater-pdk?include_prereleases&sort=semver
-   :alt: GitHub tag (latest SemVer pre-release)
+   :alt: Latest GitHub tag (including pre-releases)
    :target: https://gitHub.com/google/skywater-pdk/commit/
 
-.. image:: https://img.shields.io/github/commits-since/google/skywater-pdk/latest?include_prereleases&sort=semver
+.. image:: https://img.shields.io/github/commits-since/google/skywater-pdk/|TAG_VERSION|
-   :alt: GitHub commits since latest release (by SemVer including pre-releases)
+   :alt: GitHub commits since latest release (|TAG_VERSION|)
    :target: https://gitHub.com/google/skywater-pdk/commit/
 
-
 The SkyWater Open Source PDK is a collaboration between Google and SkyWater Technology Foundry to provide a fully open source `Process Design Kit <https://en.wikipedia.org/wiki/Process_design_kit>`_ and related resources, which can be used to create manufacturable designs at SkyWater’s facility.
 
 As of May 2020, this repository is targeting the SKY130 process node. If the SKY130 process node release is successful then in the future more advanced technology nodes may become available.
@@ -32,42 +35,42 @@ The SkyWater Open Source PDK documentation can be found at <https://skywater-pdk
    :target: https://github.com/google/skywater-pdk
    :width: 80%
 
-.. _CurrentStatus:
 
-Current Status - **Experimental Preview**
+.. include:: docs/status.rst
------------------------------------------
-
-Google and SkyWater are currently treating the current content as an **experimental preview** / **alpha release**.
-
-While the SKY130 process node and the PDK from which this open source release was derived have been used to create many designs that have been successfully manufactured commercially in significant quantities, the open source PDK is not intended to be used for production settings at this current time.
-
-To get notified about future new releases of the PDK, and other important news, please sign up on the
-`skywater-pdk-announce mailing list <https://groups.google.com/forum/#!forum/skywater-pdk-announce>`_
-[`join link <https://groups.google.com/forum/#!forum/skywater-pdk-announce/join>`_].
 
+See both the :ref:`Known Issues` section and the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to get more detailed information around currently known issues.
 
 SKY130 Process Node
--------------------
+===================
 
 The SKY130 is a mature 180nm-130nm hybrid technology originally developed internally by Cypress Semiconductor before being spun out into SkyWater Technology and made accessible to general industry. SkyWater and Google’s collaboration is now making this technology accessible to everyone!
 
 The SKY130 Process node technology stack consists of;
- * Supporting internal 1.8V with 5.0V I/Os (operable at 2.5V)
+
- * 1 level of local interconnect
+* Support for internal 1.8V with 5.0V I/Os (operable at 2.5V)
- * 5 levels of metal
+* 1 level of local interconnect
- * Is Inductor-Capable
+* 5 levels of metal
- * Has high sheet rho poly resistor
+* Is inductor-capable
- * Optional MiM capacitors
+* Has high sheet rho poly resistor
- * Includes SONOS shrunken cell
+* Optional MiM capacitors
- * Supports 10V regulated supply
+* Includes SONOS shrunken cell
- * HV extended-drain NMOS and PMOS
+* Supports 10V regulated supply
+* HV extended-drain NMOS and PMOS
+
+
+The `SKY130 Process Node`_ has is a extremely flexible offering, including many normally *optional* features as standard (feature like the local interconnect, SONOS functionality, MiM capacitors and more). This provides the designer with a **wide range** of flexibility in design choices.
+
+If your needs extend beyond the standard included functionality in the `SKY130 Process Node`_, please see `Contacting SkyWater`_ as they specializes in enabling production volume of process customization include `the addition of specialized materials like Nb, Ge, V2O5, Carbon Nanotubes <https://www.skywatertechnology.com/technology/>`_. Google and SkyWater continuing to explore new options to be included in the `SkyWater Open Source PDK`_ and `SKY130 Process Node`_ that enable new innovative solutions to traditional design problems.
 
 
 Typical usages of 130nm Process Nodes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The `130nm process <https://en.wikichip.org/wiki/130_nm_lithography_process>`_ was first commercialized around the 2001-2002 time frame and is now primarily used in the area of research, small microcontroller development, and mixed signal embedded designs such as IoT devices.
 
+A living Google document at <https://j.mp/si130nm> has been created to provide **inspiration** from what researchers, commercial entities and other groups have done with similar **sized** process nodes. As there are widely different constraints and possibilities from changes in both the manufacturing process and materials it is important **not** to assumed that the exact results found in the `130nm inspiration document <https://j.mp/si130>`_ can be identically reproduced on the `SKY130 Process Node`_.
+
+
 PDK Contents
 ============
 

docs/known_issues.rst

@@ -0,0 +1,134 @@
+Currently Known Issues
+======================
+
+This section of the documentation provides a list of currently known issues in the currently released files.
+
+.. include:: status.rst
+
+See also the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to see the latest reported issues.
+
+
+Documentation
+-------------
+
+A number of sections in the documentation still have pending TODO items. These will be fixed over the coming months.
+
+The current cell datasheets only include basic information about the cell. These datasheets will be continuously updated with new information as the generator is improved.
+
+PDK Contents
+------------
+
+Tooling Compatibility
+~~~~~~~~~~~~~~~~~~~~~
+
+Cadence Virtuoso Support
+************************
+
+The first publication of this is missing files required for optimal Cadence Virtuoso usage. These files will be released publicly at a future date after further work (see `Issue #1 <https://github.com/google/skywater-pdk/issues/1>`_).
+
+These files are;
+
+* OpenAccess versions of the cells
+* Cadence PCells, including
+
+  - Parameterized primitives including FETs, Capacitors, Resistors, Inductors, etc
+  - Seal Ring
+
+* Cadence SKILL scripts that support Virtuoso functions such as netlisting
+
+Before these files are released access to the manually created previous version of these files is available through SkyWater directly under NDA.
+
+Mentor Calibre Support
+**********************
+
+The first publication of this PDK is missing files required to do design verification with Mentor Calibre. Scripts for generating these files from the published documentation will be released at a future date  (see `Issue #2 <https://github.com/google/skywater-pdk/issues/2>`_).
+
+This includes;
+
+* Physical checking of design rules
+* Logic vs schematic checks
+* Latchup and soft design rules
+* Fill structure generator
+
+Before the scripts are released which generated the needed files for Mentor Calibre from the release documentation, manually created files which provide similar functionality are available from SkyWater directly under NDA.
+
+Specific Libraries
+------------------
+
+:lib:`sky130_fd_pr_base`
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+See `Cadence Virtuoso Support`_ section.
+
+:lib:`sky130_fd_pr_rf`
+~~~~~~~~~~~~~~~~~~~~~~
+
+The :lib:`sky130_fd_pr_rf` library is provided for references purposes only, all new designs should be based on the :lib:`sky130_fd_pr_rf2` library.
+
+See `Cadence Virtuoso Support`_ section.
+
+:lib:`sky130_fd_pr_rf2`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See `Cadence Virtuoso Support`_ section.
+
+
+:lib:`sky130_osu_sc` - SKY130 Oklahoma State University provided standard cell library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SKY130 Oklahoma State University provided standard cells library is currently empty, only a placeholder is currently provided.
+
+The SKY130 Oklahoma State University provided standard cells library will be integrated at a future date (see `Issue #10 <https://github.com/google/skywater-pdk/issues/10>`_).
+
+:lib:`sky130_fd_sp_fmlt` - SKY130 Flash Build Space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SRAM build space is currently empty, only a placeholder is currently provided.
+
+The components of the SRAM build space compatible with OpenRAM will be released at a future date (see `Issue #4 <https://github.com/google/skywater-pdk/issues/4>`_).
+
+
+:lib:`sky130_fd_sp_sram` - SKY130 SRAM Build Space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flash build space is currently empty, only a placeholder is currently provided.
+
+The components of SRAM build space will be released at a future date (see `Issue #3 <https://github.com/google/skywater-pdk/issues/3>`_).
+
+:lib:`sky130_fd_io` - SKY130 Foundry Provided IO Cells
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The IO cell library is currently empty, only a placeholder is currently provided.
+
+The IO cell library will be released at a future date (see `Issue #5 <https://github.com/google/skywater-pdk/issues/5>`_).
+
+:lib:`sky130_ef_io` - SKY130 eFabless Provided IO Cells
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The IO cell library is currently empty, only a placeholder is currently provided.
+
+The IO cell library will be released at a future date (see `Issue #9 <https://github.com/google/skywater-pdk/issues/9>`_).
+
+Design Rule Checking
+--------------------
+
+Using Mentor Calibre
+~~~~~~~~~~~~~~~~~~~~
+
+See `Mentor Calibre Support`_ section.
+
+At the moment, if you are required to use Calibre as part of your design flow, it is recommended that you also use the open source tool Magic to check for errors and fix any issues reported.
+
+Using Magic
+~~~~~~~~~~~
+
+Currently Magic does not have DRC checking rules for checking the specialized exceptions for SRAM cells in the :lib:`sky130_fd_sp_sram` SKY130 SRAM Build Space. These will be released at around the same time as the SKY130 SRAM Build Space.
+
+
+Scripts and PDK Tooling
+-----------------------
+
+A number of scripts are used to generate various files in the PDK including many of the liberty, spice files, schematic images, and much more.
+
+These scripts will be published inside the PDK at a future date (see `Issue list <https://github.com/google/skywater-pdk/issues?q=is%3Aopen+is%3Aissue+label%3Atype-todo+label%3Ascripts-python>`_).
+

docs/status.rst

@@ -0,0 +1,16 @@
+.. _CurrentStatus:
+
+Current Status - **Experimental Preview**
+-----------------------------------------
+
+Google and SkyWater are currently treating the current content as an **experimental preview** / **alpha release**.
+
+While the SKY130 process node and the PDK from which this open source release was derived have been used to create many designs that have been successfully manufactured commercially in significant quantities, the open source PDK is not intended to be used for production settings at this current time. It *should* be usable for doing test chips and initial design verification (but this is not guaranteed).
+
+Google, SkyWater and our partners are currently doing internal validation and test designs, including silicon validation or the released data and plan to publish these results.
+
+The PDK will be tagged with a production version when ready to do production design, see the `"Versioning Information" <>`_ section for a full description of the version numbering scheme.
+
+To get notified about future new releases of the PDK, and other important news, please sign up on the
+`skywater-pdk-announce mailing list <https://groups.google.com/forum/#!forum/skywater-pdk-announce>`_
+[`join link <https://groups.google.com/forum/#!forum/skywater-pdk-announce/join>`_].

docs/versioning.rst

@@ -0,0 +1,30 @@
+Version Numbering
+-----------------
+
+Version numbers for both the PDK and the supplied libraries are fully specified by a 3-digit version number followed by a git commit count and a git commit short hash.
+
+The 3-digit-number will be tagged in the associated git repository as `vX.Y.Z` and the fully specified value can be found by running `git describe` tool inside the correct git repository.
+
+The version number is broken down as `vX.Y.Z-AAA-gHHHHH`;
+
+- The letter `v`.
+
+- `X` = The "Milestone Release" Number
+
+   - **0** indicates **"alpha"** level. The IP has not undergone full qualification. Parts of the IP may be immature and untested.
+
+   - **1** indicates **"beta"** level. The IP has undergone qualification testing but has not been hardware verified.
+
+   - **2** indicates **production** level. The IP has passed qualification testing and has been hardware verified.
+
+- `Y` = The "Major Release" Number
+
+- `Z` = The "Minor Release" Number
+
+- A single hyphen character `-`
+
+- `AAA` = The git commit count since the version number was tagged.
+
+- A single hyphen character followed by the letter g `-g`
+
+- `HHHH` = A git commit short hash which uniquely identifies a specific git commit inside the associated git repository.