more doc

LICENSE

@@ -0,0 +1,28 @@
+Unless otherwise noted, LiteSATA is copyright (C) 2015 HKU.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Other authors retain ownership of their contributions. If a submission can
+reasonably be considered independently copyrightable, it's yours and we
+encourage you to claim it with appropriate copyright notices. This submission
+then falls under the "otherwise noted" category. All submissions are strongly
+encouraged to use the two-clause BSD license reproduced above.

README

@@ -9,7 +9,7 @@
        developed for HKU by M-Labs Ltd & EnjoyDigital
 
 [> Intro
------------
+---------
 LiteSATA provides a small footprint and configurable SATA gen1/2/3 core.
 
 LiteSATA is part of LiteX libraries whose aims is to lower entry level of complex
@@ -34,7 +34,7 @@ with the provided setup.py) or can be integrated with your standard design flow
 by generating the verilog rtl that you will use as a standard core.
 
 [> Features
-------------------
+-----------
 PHY:
   - OOB, COMWAKE, COMINIT
   - ALIGN inserter/remover and bytes alignment on K28.5
@@ -61,7 +61,7 @@ Frontend:
   - Synthetizable BIST
 
 [> Possibles improvements
-----------------------
+-------------------------
 - add standardized interfaces (AXI, Avalon-ST)
 - add NCQ support
 - add AES hardware encryption
@@ -71,7 +71,7 @@ Frontend:
 - add support for Xilinx 7-Series GTP/GTH (currently only 7-Series GTX are
   supported)
 - add Zynq Linux drivers.
-- ...
+- ... See below Support and Consulting :)
 
 If you want to support these features, please contact us at florent [AT]
 enjoy-digital.fr. You can also contact our partner on the public mailing list
@@ -82,29 +82,35 @@ devel [AT] lists.m-labs.hk.
 1. Install Python3 and Xilinx's Vivado software
 
 2. Obtain Migen and install it:
-  git clone https://github.com/enjoy-digital/migen
+  git clone https://github.com/m-labs/migen
   cd migen
   python3 setup.py install
   cd ..
 
 3. Obtain Miscope and install it:
-  git clone https://github.com/enjoy-digital/miscope
+  git clone https://github.com/m-labs/miscope
   cd miscope
   python3 setup.py install
   cd ..
 
 4. Obtain MiSoC:
-  git clone https://github.com/enjoy-digital/misoc --recursive
+  git clone https://github.com/m-labs/misoc --recursive
+  XXX add setup.py to MiSoC for external use of misoclib?
 
-5. Copy lite-sata in working directory and move to it.
+5. Obtain LiteSATA
+  git clone https://github.com/enjoy-digital/litesata
 
-6. Build and load design:
+6. Build and load BIST design (only for KC705 for now):
   python3 make.py all
 
-7. Test design:
-  go to test directory and run:
+7. Test design (only for KC705 for now):
+  go to ./test directory and run:
   python3 bist.py
 
+8. If you only want to build the core and use it with your
+  regular design flow:
+  python3 make.py -t core build-core
+
 [> Simulations:
   Simulations are available in ./lib/sata/test:
     - crc_tb
@@ -124,7 +130,7 @@ devel [AT] lists.m-labs.hk.
   the HDD model!
 
 [> License
-----------------------
+-----------
 LiteSATA is released under the very permissive two-clause BSD license. Under the
 terms of this license, you are authorized to use LiteSATA for closed-source
 proprietary designs.
@@ -136,19 +142,18 @@ do them if possible:
  - send us bug reports when something goes wrong
  - send us the modifications and improvements you have done to LiteSATA.
 
-[> Support
-----------------------
-We love open-source hardware and like sharing our designs with others. We think
-that providing this core with a BSD license will enable its easy reuse and
-customization without the usual restrictions of commercial cores.
+[> Support and Consulting
+--------------------------
+We love open-source hardware and like sharing our designs with others.
 
-We also offer design services and can:
-- provide you commercial support for our cores.
-- customize our cores to fit your needs and help you to integrate it in your design.
-- create custom designs for you and provide our already proven cores for free.
-- ...
+LiteSATA is developed and maintained by EnjoyDigital.
 
-So feel free to contact us, we'd love to work with you!
+If you would like to know more about LiteSATA or if you are already a happy user
+and would like to extend it for your needs, EnjoyDigital can provide standard
+commercial support as well as consulting services.
+
+So feel free to contact us, we'd love to work with you! (and eventually shorten
+the list of the possible improvements :)
 
 [> Contact
 E-mail: florent [AT] enjoy-digital.fr

doc/source/_themes/enjoydigital_sphinx_rtd_theme/footer.html

@@ -24,7 +24,7 @@
 
    {% set footer_links = [
     ('docs/getting_started/bug_reports', 'Report Bug', 'Report Bug'),
-    ('docs/introducing_litesata/litesata_license', 'Licensing', 'Licensing'),
+    ('docs/introducing_litesata/license', 'Licensing', 'Licensing'),
 	('docs/contributing/contributing', 'Contributing', 'Contributing'),
 	('docs/introducing_litesata/release_notes', 'Release notes', 'Release notes'),
 	('docs/introducing_litesata/community', 'Help', 'Contact'),

doc/source/docs/core/index.rst

@@ -3,3 +3,5 @@
 ========================
 Core
 ========================
+.. note::
+	Please contribute to this document, or support us financially to write it.

doc/source/docs/frontend/index.rst

@@ -3,3 +3,5 @@
 ========================
 Frontend
 ========================
+.. note::
+	Please contribute to this document, or support us financially to write it.

doc/source/docs/getting_started/FAQ.rst

@@ -3,3 +3,5 @@
 ===
 FAQ
 ===
+.. note::
+	Please contribute to this document.

doc/source/docs/getting_started/bug_reports.rst

@@ -3,3 +3,9 @@
 =============
 Bug Reporting
 =============
+- send us feedback and suggestions for improvements
+- send us bug reports when something goes wrong
+- send us the modifications and improvements you have done to LiteSATA.
+The use of "git format-patch" is recommended. If your submission is large and
+complex and/or you are not sure how to proceed, feel free to discuss with us
+about it.

doc/source/docs/getting_started/downloads.rst

@@ -6,25 +6,31 @@ Download and install
 1. Install Python3 and Xilinx's Vivado software
 
 2. Obtain Migen and install it:
-  - git clone https://github.com/enjoy-digital/migen
+  - git clone https://github.com/m-labs/migen
   - cd migen
   - python3 setup.py install
   - cd ..
 
 3. Obtain Miscope and install it:
-  - git clone https://github.com/enjoy-digital/miscope
+  - git clone https://github.com/m-labs/miscope
   - cd miscope
   - python3 setup.py install
   - cd ..
 
 4. Obtain MiSoC:
-  - git clone https://github.com/enjoy-digital/misoc --recursive
+  - git clone https://github.com/m-labs/misoc --recursive
+  XXX add setup.py to MiSoC for external use of misoclib?
 
-5. Copy lite-sata in working directory and move to it.
+5. Obtain LiteSATA
+  - git clone https://github.com/enjoy-digital/litesata
 
-6. Build and load design:
+6. Build and load BIST design (only for KC705 for now):
   - python3 make.py all
 
-7. Test design:
-  - go to test directory and run:
+7. Test design (only for KC705 for now):
+  - go to ./test directory and run:
   - python3 bist.py
+
+8. If you only want to build the core and use it with your
+regular design flow:
+  - python3 make.py -t core build-core

doc/source/docs/getting_started/index.rst

@@ -4,7 +4,7 @@
 Getting Started
 ===============
 
-Now you know why LiteSATA is :ref:`core for you <about-litesata>`, it's time to *get started*.
+Now you know why LiteSATA is :ref:`core for you <about>`, it's time to *get started*.
 
 This section provides a walk-through of :ref:`downloading and installing the tools`.
 
@@ -13,4 +13,5 @@ This section provides a walk-through of :ref:`downloading and installing the too
 
 	downloads
 	FAQ
+	bug_reports
 

doc/source/docs/index.rst

@@ -8,7 +8,7 @@ This comprehensive documentation set contains everything you need to know to use
 
 **Getting started:**
 
-- :ref:`introducing-litesata-index` explains what LiteSATA does, why it is needed, its limitations and its licensing. It will help you understand whether LiteSATA is the right core for you.
+- :ref:`intro-index` explains what LiteSATA does, why it is needed, its limitations and its licensing. It will help you understand whether LiteSATA is the right core for you.
 - :ref:`getting-started-index` walks you through downloading, installing and using the LiteSATA core.
 
 **LiteSATA Internals:**
@@ -27,12 +27,10 @@ The full hierarchy of articles, opened to the second level, is shown below.
 .. toctree::
 	:maxdepth: 2
 
-	introducing_litesata/index
+	intro/index
 	getting_started/index
-	sata/index
+	specification/index
 	phy/index
 	core/index
 	frontend/index
 	simulation/index
-	test/index
-	site/index

doc/source/docs/intro/about.rst

@@ -1,4 +1,4 @@
-.. _about-litesata:
+.. _about:
 
 ================
 About LiteSATA
@@ -27,10 +27,10 @@ LiteSATA can be used as a Migen/MiSoC library (by simply installing  it
 with the provided setup.py) or can be integrated with your standard design flow
 by generating the verilog rtl that you will use as a standard core.
 
-.. _about-litesata-toolchain:
+.. _about-toolchain:
 
 Features
-====================
+========
 PHY:
   - OOB, COMWAKE, COMINIT
   - ALIGN inserter/remover and bytes alignment on K28.5
@@ -58,7 +58,7 @@ Frontend:
 
 
 Possibles improvements
-====================
+======================
 - add standardized interfaces (AXI, Avalon-ST)
 - add NCQ support
 - add AES hardware encryption
@@ -68,5 +68,23 @@ Possibles improvements
 - add support for Xilinx 7-Series GTP/GTH (currently only 7-Series GTX are
   supported)
 - add Zynq Linux drivers.
-- ...
+- ... See below Support and Consulting :)
+
+Support and Consulting
+======================
+We love open-source hardware and like sharing our designs with others.
+
+LiteSATA is developed and maintained by EnjoyDigital.
+
+If you would like to know more about LiteSATA or if you are already a happy user
+and would like to extend it for your needs, EnjoyDigital can provide standard
+commercial support as well as consulting services.
+
+So feel free to contact us, we'd love to work with you! (and eventually shorten
+the list of the possible improvements :)
+
+Contact
+=======
+E-mail: florent [AT] enjoy-digital.fr
+
 

doc/source/docs/intro/index.rst

@@ -1,4 +1,4 @@
-.. _introducing-litesata-index:
+.. _intro-index:
 
 ======================
 Introducing LiteSATA
@@ -9,7 +9,7 @@ This section explains what LiteSATA does, why it is needed, its limitations and
 .. toctree::
    :maxdepth: 1
 
-   about_litesata
-   litesata_license
+   about
+   license
    release_notes
-   Talks-and-Publications
+   talks_and_publications

doc/source/docs/intro/license.rst

@@ -0,0 +1,47 @@
+.. _license:
+
+===================
+Open Source License
+===================
+
+LiteSATA is released under the very permissive two-clause BSD license. Under the
+terms of this license, you are authorized to use LiteSATA for closed-source
+proprietary designs.
+Even though we do not require you to do so, those things are awesome, so please
+do them if possible:
+ - tell us that you are using LiteSATA
+ - cite LiteSATA in publications related to research it has helped
+ - send us feedback and suggestions for improvements
+ - send us bug reports when something goes wrong
+ - send us the modifications and improvements you have done to LiteSATA.
+
+::
+
+  Unless otherwise noted, LiteSATA is copyright (C) 2015 HKU.
+
+  Redistribution and use in source and binary forms, with or without modification,
+  are permitted provided that the following conditions are met:
+
+  1. Redistributions of source code must retain the above copyright notice, this
+     list of conditions and the following disclaimer.
+  2. Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+  Other authors retain ownership of their contributions. If a submission can
+  reasonably be considered independently copyrightable, it's yours and we
+  encourage you to claim it with appropriate copyright notices. This submission
+  then falls under the "otherwise noted" category. All submissions are strongly
+  encouraged to use the two-clause BSD license reproduced above.

doc/source/docs/intro/release_notes.rst

@@ -8,3 +8,6 @@ Release Notes
 
 ChangeLog
 =========
+0.9.0:
+  - First release supporting Xilinx Kintex7.
+

doc/source/docs/intro/talks_and_publications.rst

@@ -0,0 +1,14 @@
+.. _talks-and-publications:
+
+======================
+Talks and Publications
+======================
+
+- Migen / MiSoC documentation:
+ - `User guide <http://m-labs.hk/migen.pdf>`_ (`m-labs <https://github.com/m-labs>`_)
+ - `Tutorial: An introduction to Migen <http://m-labs.hk/migen-tutorial.pdf>`_ (`m-labs <https://github.com/m-labs>`_)
+
+- Migen / MiSoC presentations:
+ - `Lecture slides <http://m-labs.hk/migen-slides.pdf>`_ (`sbourdeauducq <https://github.com/sbourdeauducq>`_)
+ - `EHSM 2012 presentation <https://www.youtube.com/watch?v=yxKMsAi_WEA>`_ (`sbourdeauducq <https://github.com/sbourdeauducq>`_)
+ - `ORCONF2014 <https://www.youtube.com/watch?v=AfEPbw4nREo>`_ (`fallen <https://github.com/fallen>`_)

doc/source/docs/introducing_litesata/Talks-and-Publications.rst

@@ -1,11 +0,0 @@
-.. _Talks-and-Publications:
-
-======================
-Talks and Publications
-======================
-
-Presentations
-=============
-
-Papers
-======

doc/source/docs/introducing_litesata/litesata_license.rst

@@ -1,16 +0,0 @@
-.. _litesata-license:
-
-===================
-Open Source License
-===================
-
-LiteSATA is released under the very permissive two-clause BSD license. Under the
-terms of this license, you are authorized to use LiteSATA for closed-source
-proprietary designs.
-Even though we do not require you to do so, those things are awesome, so please
-do them if possible:
- - tell us that you are using LiteSATA
- - cite LiteSATA in publications related to research it has helped
- - send us feedback and suggestions for improvements
- - send us bug reports when something goes wrong
- - send us the modifications and improvements you have done to LiteSATA.

doc/source/docs/phy/index.rst

@@ -3,3 +3,5 @@
 ========================
 PHY
 ========================
+.. note::
+	Please contribute to this document, or support us financially to write it.

doc/source/docs/simulation/index.rst

@@ -4,6 +4,9 @@
 Simulation
 ========================
 
+.. note::
+	Please contribute to this document, or support us financially to write it.
+
 Simulations are available in ./lib/sata/test:
   - crc_tb
   - scrambler_tb

doc/source/docs/specification/index.rst

@@ -1,7 +1,7 @@
 .. _sata-index:
 
 ========================
-SATA
+SATA Specification
 ========================
 
 .. note::
@@ -14,10 +14,12 @@ and 8b/10b encoding. The link supports full duplex but the protocol only permits
 in one direction at a time. The other non-data direction is used for flow control of the
 data stream
 
-.. image:: sata_layers.png
+.. figure:: sata_layers.png
    :scale: 50 %
    :align: center
 
+   SATA layers.
+
 SATA’s architecture consists of four layers, Application, Transport, Link, and Physical.
 The Application layer is responsible for overall ATA commands and of controlling SATA
 register accesses. The transport layer places control information and data to be transferred between
@@ -34,10 +36,12 @@ into four bytes. Where each pair of bytes represent a word and a pair of words
 represent a Dword. In this way it’s easy to see that odd number of bytes is not
 allowed in SATA communication.
 
-.. image:: byte_word_dword.png
+.. figure:: byte_word_dword.png
    :scale: 50 %
    :align: center
 
+   Byte, Word, Dword definitions.
+
 The Dwords can be represented by either a data Dword or a so called primitive. A
 primitive is a predefined Dword like for example start of frame (SOF) and end
 of frame (EOF).
@@ -78,10 +82,12 @@ drive their output pins to the same voltage, resulting in a reduced difference a
 when a preset threshold limit is reached the receiver can recognize the signal as
 OOB.
 
-.. image:: oob_signals.png
+.. figure:: oob_signals.png
    :scale: 50 %
    :align: center
 
+   OOB signals.
+
 As can be seen in the figure there are three types of (actually two
 since COMINIT and COMRESET are equal) valid OOB signals where bursts of
 six ALIGN are sent with different timing. The importance in the signaling lies
@@ -95,10 +101,12 @@ COMWAKE back. If this procedure is finished within a correct time the OOB signal
 ends and the differential communication can proceed with determining the link speed
 (right part of the figure).
 
-.. image:: oob_sequence.png
+.. figure:: oob_sequence.png
    :scale: 50 %
    :align: center
 
+   OOB init sequence.
+
 Physical Layer
 ==============
 This section describes the physical interface towards the actual SATA link.
@@ -136,10 +144,12 @@ by applying the 32-bits generator polynomial G(x) in Equation on every bit in
 every non-primitive Dword in a FIS and then summarize (modulo 2) all these terms
 together with the Initial Value. The CRC is fixed to value of 0x52325032.
 
-.. image:: crc.png
+.. figure:: crc.png
    :scale: 50 %
    :align: center
 
+   CRC polynom.
+
 Scrambling a FIS reduces EMI by spreading the noise over a broader frequency
 spectrum. The scrambling algorithm can be expressed as a polynomial or as a linear
 feedback shift register. The scrambling creates a pseudorandom bit pattern of the
@@ -147,10 +157,12 @@ data that reduces EMI. The algorithm resets to a of value of 0xFFFF every time a
 is encountered at the scrambler. The de-scrambler uses the same algorithm on scrambled
 data so it retakes its original form.
 
-.. image:: scrambler.png
+.. figure:: scrambler.png
    :scale: 50 %
    :align: center
 
+   Scrambler LFSR polynom.
+
 It is important that the CRC calculations are made at original data and that
 the scrambling/de-scrambling are made between the CRC and the 8b/10b encoding/decoding.
 The flow control between host and device is managed by sending
@@ -193,7 +205,6 @@ Command Layer
 The command layer tells the transport layer what kind of FISes to send and receive
 for each specific command and in which order those FISes are expexted to be delivered.
 
-
 .. note::
 	This chapter is a lightly modified version of the excellent SATA summerization found in Chapter 2 of Erik Landström's Thesis_.
 

doc/source/docs/test/index.rst

@@ -4,6 +4,9 @@
 Test
 ========================
 
+.. note::
+	Please contribute to this document, or support us financially to write it.
+
 A synthetizable BIST is provided and can be controlled with ./test/bist.py.
 By using Miscope and the provided ./test/test_link.py example you are able to
 visualize the internal logic of the design and even inject the captured data in

doc/source/index.rst

@@ -16,9 +16,9 @@ News
 .. toctree::
 	:hidden:
 
-	docs/introducing_litesata/index
+	docs/intro/index
 	docs/getting_started/index
-	docs/sata/index
+	docs/specification/index
 	docs/phy/index
 	docs/core/index
 	docs/frontend/index