From 319a4a7f51525c8a5dcf2e524fc858c9ff1a9a22 Mon Sep 17 00:00:00 2001 From: Florent Kermarrec Date: Thu, 22 Jan 2015 17:44:04 +0100 Subject: [PATCH] more doc --- LICENSE | 28 ++++++++++ README | 51 ++++++++++-------- .../enjoydigital_sphinx_rtd_theme/footer.html | 2 +- doc/source/docs/core/index.rst | 2 + doc/source/docs/frontend/index.rst | 2 + doc/source/docs/getting_started/FAQ.rst | 2 + .../docs/getting_started/bug_reports.rst | 6 +++ doc/source/docs/getting_started/downloads.rst | 20 ++++--- doc/source/docs/getting_started/index.rst | 3 +- doc/source/docs/index.rst | 8 ++- .../about_litesata.rst => intro/about.rst} | 28 ++++++++-- .../community.rst | 0 .../{introducing_litesata => intro}/index.rst | 8 +-- doc/source/docs/intro/license.rst | 47 ++++++++++++++++ .../release_notes.rst | 3 ++ .../docs/intro/talks_and_publications.rst | 14 +++++ .../Talks-and-Publications.rst | 11 ---- .../introducing_litesata/litesata_license.rst | 16 ------ doc/source/docs/phy/index.rst | 2 + doc/source/docs/simulation/index.rst | 3 ++ .../byte_word_dword.png | Bin .../docs/{sata => specification}/crc.png | Bin .../docs/{sata => specification}/index.rst | 27 +++++++--- .../{sata => specification}/oob_sequence.png | Bin .../{sata => specification}/oob_signals.png | Bin .../{sata => specification}/sata_layers.png | Bin .../{sata => specification}/scrambler.png | Bin doc/source/docs/test/index.rst | 3 ++ doc/source/index.rst | 4 +- 29 files changed, 207 insertions(+), 83 deletions(-) create mode 100644 LICENSE rename doc/source/docs/{introducing_litesata/about_litesata.rst => intro/about.rst} (77%) rename doc/source/docs/{introducing_litesata => intro}/community.rst (100%) rename doc/source/docs/{introducing_litesata => intro}/index.rst (78%) create mode 100644 doc/source/docs/intro/license.rst rename doc/source/docs/{introducing_litesata => intro}/release_notes.rst (65%) create mode 100644 doc/source/docs/intro/talks_and_publications.rst delete mode 100644 doc/source/docs/introducing_litesata/Talks-and-Publications.rst delete mode 100644 doc/source/docs/introducing_litesata/litesata_license.rst rename doc/source/docs/{sata => specification}/byte_word_dword.png (100%) rename doc/source/docs/{sata => specification}/crc.png (100%) rename doc/source/docs/{sata => specification}/index.rst (96%) rename doc/source/docs/{sata => specification}/oob_sequence.png (100%) rename doc/source/docs/{sata => specification}/oob_signals.png (100%) rename doc/source/docs/{sata => specification}/sata_layers.png (100%) rename doc/source/docs/{sata => specification}/scrambler.png (100%) diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..f35c9bfc --- /dev/null +++ b/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. diff --git a/README b/README index 9e45ea86..881bf1be 100644 --- a/README +++ b/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. + +LiteSATA is developed and maintained by EnjoyDigital. -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. -- ... +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! +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 diff --git a/doc/source/_themes/enjoydigital_sphinx_rtd_theme/footer.html b/doc/source/_themes/enjoydigital_sphinx_rtd_theme/footer.html index 1cdc7286..fd017c5c 100644 --- a/doc/source/_themes/enjoydigital_sphinx_rtd_theme/footer.html +++ b/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'), diff --git a/doc/source/docs/core/index.rst b/doc/source/docs/core/index.rst index 6afe9ac2..33ae1eab 100644 --- a/doc/source/docs/core/index.rst +++ b/doc/source/docs/core/index.rst @@ -3,3 +3,5 @@ ======================== Core ======================== +.. note:: + Please contribute to this document, or support us financially to write it. \ No newline at end of file diff --git a/doc/source/docs/frontend/index.rst b/doc/source/docs/frontend/index.rst index 49a2ed81..d112402e 100644 --- a/doc/source/docs/frontend/index.rst +++ b/doc/source/docs/frontend/index.rst @@ -3,3 +3,5 @@ ======================== Frontend ======================== +.. note:: + Please contribute to this document, or support us financially to write it. diff --git a/doc/source/docs/getting_started/FAQ.rst b/doc/source/docs/getting_started/FAQ.rst index f9408728..87c3401f 100644 --- a/doc/source/docs/getting_started/FAQ.rst +++ b/doc/source/docs/getting_started/FAQ.rst @@ -3,3 +3,5 @@ === FAQ === +.. note:: + Please contribute to this document. diff --git a/doc/source/docs/getting_started/bug_reports.rst b/doc/source/docs/getting_started/bug_reports.rst index 7bcbfaf4..dc5b0553 100644 --- a/doc/source/docs/getting_started/bug_reports.rst +++ b/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. \ No newline at end of file diff --git a/doc/source/docs/getting_started/downloads.rst b/doc/source/docs/getting_started/downloads.rst index c906e555..66051831 100644 --- a/doc/source/docs/getting_started/downloads.rst +++ b/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 \ No newline at end of file diff --git a/doc/source/docs/getting_started/index.rst b/doc/source/docs/getting_started/index.rst index e244ece7..8eb05973 100644 --- a/doc/source/docs/getting_started/index.rst +++ b/doc/source/docs/getting_started/index.rst @@ -4,7 +4,7 @@ Getting Started =============== -Now you know why LiteSATA is :ref:`core for you `, it's time to *get started*. +Now you know why LiteSATA is :ref:`core for you `, 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 diff --git a/doc/source/docs/index.rst b/doc/source/docs/index.rst index 55baab49..2b09fefc 100644 --- a/doc/source/docs/index.rst +++ b/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 diff --git a/doc/source/docs/introducing_litesata/about_litesata.rst b/doc/source/docs/intro/about.rst similarity index 77% rename from doc/source/docs/introducing_litesata/about_litesata.rst rename to doc/source/docs/intro/about.rst index 28385021..e27d930c 100644 --- a/doc/source/docs/introducing_litesata/about_litesata.rst +++ b/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 + diff --git a/doc/source/docs/introducing_litesata/community.rst b/doc/source/docs/intro/community.rst similarity index 100% rename from doc/source/docs/introducing_litesata/community.rst rename to doc/source/docs/intro/community.rst diff --git a/doc/source/docs/introducing_litesata/index.rst b/doc/source/docs/intro/index.rst similarity index 78% rename from doc/source/docs/introducing_litesata/index.rst rename to doc/source/docs/intro/index.rst index 077a1051..ab24dc2d 100644 --- a/doc/source/docs/introducing_litesata/index.rst +++ b/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 diff --git a/doc/source/docs/intro/license.rst b/doc/source/docs/intro/license.rst new file mode 100644 index 00000000..86a41c88 --- /dev/null +++ b/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. diff --git a/doc/source/docs/introducing_litesata/release_notes.rst b/doc/source/docs/intro/release_notes.rst similarity index 65% rename from doc/source/docs/introducing_litesata/release_notes.rst rename to doc/source/docs/intro/release_notes.rst index 24994777..28801943 100644 --- a/doc/source/docs/introducing_litesata/release_notes.rst +++ b/doc/source/docs/intro/release_notes.rst @@ -8,3 +8,6 @@ Release Notes ChangeLog ========= +0.9.0: + - First release supporting Xilinx Kintex7. + diff --git a/doc/source/docs/intro/talks_and_publications.rst b/doc/source/docs/intro/talks_and_publications.rst new file mode 100644 index 00000000..071a4e6a --- /dev/null +++ b/doc/source/docs/intro/talks_and_publications.rst @@ -0,0 +1,14 @@ +.. _talks-and-publications: + +====================== +Talks and Publications +====================== + +- Migen / MiSoC documentation: + - `User guide `_ (`m-labs `_) + - `Tutorial: An introduction to Migen `_ (`m-labs `_) + +- Migen / MiSoC presentations: + - `Lecture slides `_ (`sbourdeauducq `_) + - `EHSM 2012 presentation `_ (`sbourdeauducq `_) + - `ORCONF2014 `_ (`fallen `_) diff --git a/doc/source/docs/introducing_litesata/Talks-and-Publications.rst b/doc/source/docs/introducing_litesata/Talks-and-Publications.rst deleted file mode 100644 index d08633b3..00000000 --- a/doc/source/docs/introducing_litesata/Talks-and-Publications.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _Talks-and-Publications: - -====================== -Talks and Publications -====================== - -Presentations -============= - -Papers -====== diff --git a/doc/source/docs/introducing_litesata/litesata_license.rst b/doc/source/docs/introducing_litesata/litesata_license.rst deleted file mode 100644 index 3a4529b5..00000000 --- a/doc/source/docs/introducing_litesata/litesata_license.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/doc/source/docs/phy/index.rst b/doc/source/docs/phy/index.rst index 6ca1d192..c1193cad 100644 --- a/doc/source/docs/phy/index.rst +++ b/doc/source/docs/phy/index.rst @@ -3,3 +3,5 @@ ======================== PHY ======================== +.. note:: + Please contribute to this document, or support us financially to write it. \ No newline at end of file diff --git a/doc/source/docs/simulation/index.rst b/doc/source/docs/simulation/index.rst index 23900daf..18640513 100644 --- a/doc/source/docs/simulation/index.rst +++ b/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 diff --git a/doc/source/docs/sata/byte_word_dword.png b/doc/source/docs/specification/byte_word_dword.png similarity index 100% rename from doc/source/docs/sata/byte_word_dword.png rename to doc/source/docs/specification/byte_word_dword.png diff --git a/doc/source/docs/sata/crc.png b/doc/source/docs/specification/crc.png similarity index 100% rename from doc/source/docs/sata/crc.png rename to doc/source/docs/specification/crc.png diff --git a/doc/source/docs/sata/index.rst b/doc/source/docs/specification/index.rst similarity index 96% rename from doc/source/docs/sata/index.rst rename to doc/source/docs/specification/index.rst index 35a3f458..660ea384 100644 --- a/doc/source/docs/sata/index.rst +++ b/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_. diff --git a/doc/source/docs/sata/oob_sequence.png b/doc/source/docs/specification/oob_sequence.png similarity index 100% rename from doc/source/docs/sata/oob_sequence.png rename to doc/source/docs/specification/oob_sequence.png diff --git a/doc/source/docs/sata/oob_signals.png b/doc/source/docs/specification/oob_signals.png similarity index 100% rename from doc/source/docs/sata/oob_signals.png rename to doc/source/docs/specification/oob_signals.png diff --git a/doc/source/docs/sata/sata_layers.png b/doc/source/docs/specification/sata_layers.png similarity index 100% rename from doc/source/docs/sata/sata_layers.png rename to doc/source/docs/specification/sata_layers.png diff --git a/doc/source/docs/sata/scrambler.png b/doc/source/docs/specification/scrambler.png similarity index 100% rename from doc/source/docs/sata/scrambler.png rename to doc/source/docs/specification/scrambler.png diff --git a/doc/source/docs/test/index.rst b/doc/source/docs/test/index.rst index 285e8519..d09426d5 100644 --- a/doc/source/docs/test/index.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index de660894..846392d0 100644 --- a/doc/source/index.rst +++ b/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 -- 2.30.2