From: Florent Kermarrec Date: Thu, 22 Jan 2015 16:44:04 +0000 (+0100) Subject: more doc X-Git-Tag: 24jan2021_ls180~2572^2~22 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=319a4a7f51525c8a5dcf2e524fc858c9ff1a9a22;p=litex.git more doc --- 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/intro/about.rst b/doc/source/docs/intro/about.rst new file mode 100644 index 00000000..e27d930c --- /dev/null +++ b/doc/source/docs/intro/about.rst @@ -0,0 +1,90 @@ +.. _about: + +================ +About LiteSATA +================ + +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 +FPGA IP cores by providing simple, elegant and efficient implementations of +components used in today's SoC such as Ethernet, SATA, PCIe, SDRAM Controller... + +The core uses simple and specific streaming buses and will provides in the future +adapters to use standardized AXI or Avalon-ST streaming buses. + +Since Python is used to describe the HDL, the core is highly and easily +configurable. + +The synthetizable BIST can be used as a starting point to integrate SATA in +your own SoC. + +LiteSATA uses technologies developed in partnership with M-Labs Ltd: + - Migen enables generating HDL with Python in an efficient way. + - MiSoC provides the basic blocks to build a powerful and small footprint SoC. + +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-toolchain: + +Features +======== +PHY: + - OOB, COMWAKE, COMINIT + - ALIGN inserter/remover and bytes alignment on K28.5 + - 8B/10B encoding/decoding in transceiver + - Errors detection and reporting + - 32 bits interface + - 1.5/3.0/6.0GBps supported speeds (respectively 37.5/75/150MHz system clk) +Core: + Link: + - CONT inserter/remover + - Scrambling/Descrambling of data + - CRC inserter/checker + - HOLD insertion/detection + - Errors detection and reporting + Transport/Command: + - Easy to use user interfaces (Can be used with or without CPU) + - 48 bits sector addressing + - 3 supported commands: READ_DMA(_EXT), WRITE_DMA(_EXT), IDENTIFY_DEVICE + - Errors detection and reporting + +Frontend: + - Configurable crossbar (simply use core.crossbar.get_port() to add a new port!) + - Ports arbitration transparent to the user + - Synthetizable BIST + + +Possibles improvements +====================== +- add standardized interfaces (AXI, Avalon-ST) +- add NCQ support +- add AES hardware encryption +- add on-the-flow compression/decompression +- add support for Altera PHYs. +- add support for Lattice PHYs. +- 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/intro/community.rst b/doc/source/docs/intro/community.rst new file mode 100644 index 00000000..6d1ef429 --- /dev/null +++ b/doc/source/docs/intro/community.rst @@ -0,0 +1,5 @@ +.. _community: + +========= +Community +========= diff --git a/doc/source/docs/intro/index.rst b/doc/source/docs/intro/index.rst new file mode 100644 index 00000000..ab24dc2d --- /dev/null +++ b/doc/source/docs/intro/index.rst @@ -0,0 +1,15 @@ +.. _intro-index: + +====================== +Introducing LiteSATA +====================== + +This section explains what LiteSATA does, why it is needed, its limitations and its licensing. After reading, you will understand whether LiteSATA is the right core for you, and where to go if you have :ref:`further questions `. + +.. toctree:: + :maxdepth: 1 + + about + license + release_notes + 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/intro/release_notes.rst b/doc/source/docs/intro/release_notes.rst new file mode 100644 index 00000000..28801943 --- /dev/null +++ b/doc/source/docs/intro/release_notes.rst @@ -0,0 +1,13 @@ +.. _release-notes: + +============= +Release Notes +============= + +.. _ChangeLog: + +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/about_litesata.rst b/doc/source/docs/introducing_litesata/about_litesata.rst deleted file mode 100644 index 28385021..00000000 --- a/doc/source/docs/introducing_litesata/about_litesata.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _about-litesata: - -================ -About LiteSATA -================ - -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 -FPGA IP cores by providing simple, elegant and efficient implementations of -components used in today's SoC such as Ethernet, SATA, PCIe, SDRAM Controller... - -The core uses simple and specific streaming buses and will provides in the future -adapters to use standardized AXI or Avalon-ST streaming buses. - -Since Python is used to describe the HDL, the core is highly and easily -configurable. - -The synthetizable BIST can be used as a starting point to integrate SATA in -your own SoC. - -LiteSATA uses technologies developed in partnership with M-Labs Ltd: - - Migen enables generating HDL with Python in an efficient way. - - MiSoC provides the basic blocks to build a powerful and small footprint SoC. - -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: - -Features -==================== -PHY: - - OOB, COMWAKE, COMINIT - - ALIGN inserter/remover and bytes alignment on K28.5 - - 8B/10B encoding/decoding in transceiver - - Errors detection and reporting - - 32 bits interface - - 1.5/3.0/6.0GBps supported speeds (respectively 37.5/75/150MHz system clk) -Core: - Link: - - CONT inserter/remover - - Scrambling/Descrambling of data - - CRC inserter/checker - - HOLD insertion/detection - - Errors detection and reporting - Transport/Command: - - Easy to use user interfaces (Can be used with or without CPU) - - 48 bits sector addressing - - 3 supported commands: READ_DMA(_EXT), WRITE_DMA(_EXT), IDENTIFY_DEVICE - - Errors detection and reporting - -Frontend: - - Configurable crossbar (simply use core.crossbar.get_port() to add a new port!) - - Ports arbitration transparent to the user - - Synthetizable BIST - - -Possibles improvements -==================== -- add standardized interfaces (AXI, Avalon-ST) -- add NCQ support -- add AES hardware encryption -- add on-the-flow compression/decompression -- add support for Altera PHYs. -- add support for Lattice PHYs. -- add support for Xilinx 7-Series GTP/GTH (currently only 7-Series GTX are - supported) -- add Zynq Linux drivers. -- ... - diff --git a/doc/source/docs/introducing_litesata/community.rst b/doc/source/docs/introducing_litesata/community.rst deleted file mode 100644 index 6d1ef429..00000000 --- a/doc/source/docs/introducing_litesata/community.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _community: - -========= -Community -========= diff --git a/doc/source/docs/introducing_litesata/index.rst b/doc/source/docs/introducing_litesata/index.rst deleted file mode 100644 index 077a1051..00000000 --- a/doc/source/docs/introducing_litesata/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _introducing-litesata-index: - -====================== -Introducing LiteSATA -====================== - -This section explains what LiteSATA does, why it is needed, its limitations and its licensing. After reading, you will understand whether LiteSATA is the right core for you, and where to go if you have :ref:`further questions `. - -.. toctree:: - :maxdepth: 1 - - about_litesata - litesata_license - release_notes - Talks-and-Publications 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/introducing_litesata/release_notes.rst b/doc/source/docs/introducing_litesata/release_notes.rst deleted file mode 100644 index 24994777..00000000 --- a/doc/source/docs/introducing_litesata/release_notes.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _release-notes: - -============= -Release Notes -============= - -.. _ChangeLog: - -ChangeLog -========= 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/sata/byte_word_dword.png b/doc/source/docs/sata/byte_word_dword.png deleted file mode 100644 index 2d56ca29..00000000 Binary files a/doc/source/docs/sata/byte_word_dword.png and /dev/null differ diff --git a/doc/source/docs/sata/crc.png b/doc/source/docs/sata/crc.png deleted file mode 100644 index 5fc0337f..00000000 Binary files a/doc/source/docs/sata/crc.png and /dev/null differ diff --git a/doc/source/docs/sata/index.rst b/doc/source/docs/sata/index.rst deleted file mode 100644 index 35a3f458..00000000 --- a/doc/source/docs/sata/index.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. _sata-index: - -======================== -SATA -======================== - -.. note:: - This chapter is a lightly modified version of the excellent SATA summerization found in Chapter 2 of Erik Landström's Thesis_. - -Serial Advanced Technology Attachment (SATA) is a serial link replacement of -Parallel ATA (PATA), both standards for communication with mass storage devices. -This high-speed serial link is a differential layer that utilizes Gigabit technology -and 8b/10b encoding. The link supports full duplex but the protocol only permits frames -in one direction at a time. The other non-data direction is used for flow control of the -data stream - -.. image:: sata_layers.png - :scale: 50 % - :align: center - -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 -the host and corresponding SATA device in a data packets. One such packet is called a frame -information structure (FIS). The Link layer is responsible for taking data from a FIS and -encode/decode it using 8b/10b. It also inserts control characters for flow control and calculates -the cyclic redundancy check (CRC) for error detection. Finally the Phy layer’s task is to deliver -and receive the encoded serial data stream on the wire. - -Dword - Data Representation -=========================== -In the SATA standard the smallest allowed data is a Dword, its 32 bits are divided -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 - :scale: 50 % - :align: center - -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). - -Primitives -========== -Primitives are Dwords with a purpose to enable and control the serial communication. -They all begin with a control character followed by three other characters to -fill up the Dword. The control character makes it easy to recognize a primitive from -a ordinary Dword of a frame. There is 18 different primitives, all with a dedicated -task like for example mark a frame with a SOF or to provide synchronization -with the SYNC. - -8b/10b - Encoding -================= -8b/10b encoding is rather common in high speed applications, it’s used to provide -bounded disparity but still provide enough toggling to make clock recovery possible -(synchronize internal clock with the data stream). The bounded disparity means -that in a string of twenty bits the difference between zeros and ones shall be -2, 0, -or 2 and with a maximum runlength of five. The drawback is the created overhead -of two bits per byte making the actual transfer speed of for example 1.5 Gbps link -to 1.2 Gbps, a loss of 20 %. Since the 8b/10b extends the possible alphabet from -256 symbols to 1024 it can provide detection and encoding of special characters -(also called k-characters) in an easy and effective way. This is used in the SATA -standard by encoding every primitive as such special characters. - - -Out of Band Signaling -====================== -Since SATA devices and hosts always sends junk over its differential channels, -when it is idle (otherwise the link is considered lost), there has to be a way of -recognizing a signal before a link has been initialized. For this SATA uses so -called out of band signaling (OOB) to initialize a connection between a host and a -device. The OOB mechanism supports low speed transmission over a high speed -connection, such as a SATA link. The OOB signals are non-differential but are sent -over a differential channel. This is possible by letting the differential transmitters -drive their output pins to the same voltage, resulting in a reduced difference and -when a preset threshold limit is reached the receiver can recognize the signal as -OOB. - -.. image:: oob_signals.png - :scale: 50 % - :align: center - -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 -in the timing, it does not really matter if an ALIGN or something else are sent -because the receiver only detects the drop of voltage difference between rx+ and -rx-. In the next figure the complete startup sequence is visualized and -the calibration steps in it are optional to implement. The host sends COMRESET -until the device is powered on and can respond with a COMINIT. Upon reception -of the COMINIT the host sends a COMWAKE to the device which shall send a -COMWAKE back. If this procedure is finished within a correct time the OOB signaling -ends and the differential communication can proceed with determining the link speed -(right part of the figure). - -.. image:: oob_sequence.png - :scale: 50 % - :align: center - -Physical Layer -============== -This section describes the physical interface towards the actual SATA link. -The features of the phy can be summarized to: - - Transmit/Receive a 1.5 Gbps, 3.0 or 6.0 Gbps differential signal - - Speed negotiation - - OOB detection and transmission - - Serialize a 10, 20, or other width parallel data from the link layer - - Extract data from the serial data stream - - Parallelize the data stream and send it to the link layer - - Handle spread spectrum clocking (SSC), a clock modulation technique used - to reduce unintentional interference to radio signals - -At startup the physical layer is in its OOB state and after a link has been initiated -it changes to Idle Bus condition and normal SATA communication is now -supported. Since the SATA connection is noisy the physical layer detects a frame -when it receives a SOF primitive and it will keep on listening to the incoming -signal until an EOF primitive is received. Except from FIS the SATA traffic -also consists of single primitives which all are easy for the PHY to recognize because -of their starting control character. - -Link Layer -========== -This section describes the SATA link layer. -The link layer’s major tasks are: - - Flow control - - Encapsulate FISes received from transport layer - - CRC generation and CRC check - - FIS scrambling and de-scrambling - - 8b/10b encoding/decoding - -A FIS is framed between a SOF and a EOF creating the boundaries of a frame. -The last Dword before a EOF is the CRC value for the FIS. The CRC is calculated -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 - :scale: 50 % - :align: center - -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 -data that reduces EMI. The algorithm resets to a of value of 0xFFFF every time a SOF -is encountered at the scrambler. The de-scrambler uses the same algorithm on scrambled -data so it retakes its original form. - -.. image:: scrambler.png - :scale: 50 % - :align: center - -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 -primitives to one another telling its status (which originates from the transport -layer). Some of these primitives can be inserted into FIS. Primitives are not -supposed to be scrambled or added to the CRC sum. Internally the flow control -are regulated by signaling between the layers. - -Transport Layer -=============== -The main task for the SATA transport layer is to handle FISes and a brief description -of the layer’s features follows: - - Flow control - - Error control - - Error reporting - - FIS construction - - FIS decomposition - - FIS buffering for retransmission - -There are eight types of FISes each with its specific 8-bit ID and unique header. -FISes vary in size from 1 Dword up to 2049 Dwords. The number of bytes in a -FIS are always a multiple of four so the transport layer has to fill up with zeros if -there are bytes or bits missing for an entire Dword. -The flow control in this case is only to report to the link layer that the data buffers -are close to over- or underflow. Errors detected are supposed to be reported to -the application layer and the detectable errors are: - - Errors from lower layers like 8b/10b disparity error or CRC errors. - - SATA state or protocol errors caused by standard violation. - - Frame errors like malformed header. - - Internal transport layer errors like buffer overflow. - -Errors are handled in different ways, for example are resending of complete FISes -supported for all kind of FISes besides the data FISes (and the BIST FIS which -is used typically during testing), because that would need buffers in size of 8192 -bytes (maximum supported FIS size). The max sized non-data FIS is 28 bytes so -the costs of a large buffer can be spared. - -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_. - -.. _Thesis: http://www.diva-portal.org/smash/get/diva2:207798/FULLTEXT01.pdf diff --git a/doc/source/docs/sata/oob_sequence.png b/doc/source/docs/sata/oob_sequence.png deleted file mode 100644 index 8edacede..00000000 Binary files a/doc/source/docs/sata/oob_sequence.png and /dev/null differ diff --git a/doc/source/docs/sata/oob_signals.png b/doc/source/docs/sata/oob_signals.png deleted file mode 100644 index 9fd831b6..00000000 Binary files a/doc/source/docs/sata/oob_signals.png and /dev/null differ diff --git a/doc/source/docs/sata/sata_layers.png b/doc/source/docs/sata/sata_layers.png deleted file mode 100644 index 5b5cdead..00000000 Binary files a/doc/source/docs/sata/sata_layers.png and /dev/null differ diff --git a/doc/source/docs/sata/scrambler.png b/doc/source/docs/sata/scrambler.png deleted file mode 100644 index 6139f28d..00000000 Binary files a/doc/source/docs/sata/scrambler.png and /dev/null differ 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/specification/byte_word_dword.png b/doc/source/docs/specification/byte_word_dword.png new file mode 100644 index 00000000..2d56ca29 Binary files /dev/null and b/doc/source/docs/specification/byte_word_dword.png differ diff --git a/doc/source/docs/specification/crc.png b/doc/source/docs/specification/crc.png new file mode 100644 index 00000000..5fc0337f Binary files /dev/null and b/doc/source/docs/specification/crc.png differ diff --git a/doc/source/docs/specification/index.rst b/doc/source/docs/specification/index.rst new file mode 100644 index 00000000..660ea384 --- /dev/null +++ b/doc/source/docs/specification/index.rst @@ -0,0 +1,211 @@ +.. _sata-index: + +======================== +SATA Specification +======================== + +.. note:: + This chapter is a lightly modified version of the excellent SATA summerization found in Chapter 2 of Erik Landström's Thesis_. + +Serial Advanced Technology Attachment (SATA) is a serial link replacement of +Parallel ATA (PATA), both standards for communication with mass storage devices. +This high-speed serial link is a differential layer that utilizes Gigabit technology +and 8b/10b encoding. The link supports full duplex but the protocol only permits frames +in one direction at a time. The other non-data direction is used for flow control of the +data stream + +.. 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 +the host and corresponding SATA device in a data packets. One such packet is called a frame +information structure (FIS). The Link layer is responsible for taking data from a FIS and +encode/decode it using 8b/10b. It also inserts control characters for flow control and calculates +the cyclic redundancy check (CRC) for error detection. Finally the Phy layer’s task is to deliver +and receive the encoded serial data stream on the wire. + +Dword - Data Representation +=========================== +In the SATA standard the smallest allowed data is a Dword, its 32 bits are divided +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. + +.. 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). + +Primitives +========== +Primitives are Dwords with a purpose to enable and control the serial communication. +They all begin with a control character followed by three other characters to +fill up the Dword. The control character makes it easy to recognize a primitive from +a ordinary Dword of a frame. There is 18 different primitives, all with a dedicated +task like for example mark a frame with a SOF or to provide synchronization +with the SYNC. + +8b/10b - Encoding +================= +8b/10b encoding is rather common in high speed applications, it’s used to provide +bounded disparity but still provide enough toggling to make clock recovery possible +(synchronize internal clock with the data stream). The bounded disparity means +that in a string of twenty bits the difference between zeros and ones shall be -2, 0, +or 2 and with a maximum runlength of five. The drawback is the created overhead +of two bits per byte making the actual transfer speed of for example 1.5 Gbps link +to 1.2 Gbps, a loss of 20 %. Since the 8b/10b extends the possible alphabet from +256 symbols to 1024 it can provide detection and encoding of special characters +(also called k-characters) in an easy and effective way. This is used in the SATA +standard by encoding every primitive as such special characters. + + +Out of Band Signaling +====================== +Since SATA devices and hosts always sends junk over its differential channels, +when it is idle (otherwise the link is considered lost), there has to be a way of +recognizing a signal before a link has been initialized. For this SATA uses so +called out of band signaling (OOB) to initialize a connection between a host and a +device. The OOB mechanism supports low speed transmission over a high speed +connection, such as a SATA link. The OOB signals are non-differential but are sent +over a differential channel. This is possible by letting the differential transmitters +drive their output pins to the same voltage, resulting in a reduced difference and +when a preset threshold limit is reached the receiver can recognize the signal as +OOB. + +.. 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 +in the timing, it does not really matter if an ALIGN or something else are sent +because the receiver only detects the drop of voltage difference between rx+ and +rx-. In the next figure the complete startup sequence is visualized and +the calibration steps in it are optional to implement. The host sends COMRESET +until the device is powered on and can respond with a COMINIT. Upon reception +of the COMINIT the host sends a COMWAKE to the device which shall send a +COMWAKE back. If this procedure is finished within a correct time the OOB signaling +ends and the differential communication can proceed with determining the link speed +(right part of the figure). + +.. figure:: oob_sequence.png + :scale: 50 % + :align: center + + OOB init sequence. + +Physical Layer +============== +This section describes the physical interface towards the actual SATA link. +The features of the phy can be summarized to: + - Transmit/Receive a 1.5 Gbps, 3.0 or 6.0 Gbps differential signal + - Speed negotiation + - OOB detection and transmission + - Serialize a 10, 20, or other width parallel data from the link layer + - Extract data from the serial data stream + - Parallelize the data stream and send it to the link layer + - Handle spread spectrum clocking (SSC), a clock modulation technique used + to reduce unintentional interference to radio signals + +At startup the physical layer is in its OOB state and after a link has been initiated +it changes to Idle Bus condition and normal SATA communication is now +supported. Since the SATA connection is noisy the physical layer detects a frame +when it receives a SOF primitive and it will keep on listening to the incoming +signal until an EOF primitive is received. Except from FIS the SATA traffic +also consists of single primitives which all are easy for the PHY to recognize because +of their starting control character. + +Link Layer +========== +This section describes the SATA link layer. +The link layer’s major tasks are: + - Flow control + - Encapsulate FISes received from transport layer + - CRC generation and CRC check + - FIS scrambling and de-scrambling + - 8b/10b encoding/decoding + +A FIS is framed between a SOF and a EOF creating the boundaries of a frame. +The last Dword before a EOF is the CRC value for the FIS. The CRC is calculated +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. + +.. 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 +data that reduces EMI. The algorithm resets to a of value of 0xFFFF every time a SOF +is encountered at the scrambler. The de-scrambler uses the same algorithm on scrambled +data so it retakes its original form. + +.. 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 +primitives to one another telling its status (which originates from the transport +layer). Some of these primitives can be inserted into FIS. Primitives are not +supposed to be scrambled or added to the CRC sum. Internally the flow control +are regulated by signaling between the layers. + +Transport Layer +=============== +The main task for the SATA transport layer is to handle FISes and a brief description +of the layer’s features follows: + - Flow control + - Error control + - Error reporting + - FIS construction + - FIS decomposition + - FIS buffering for retransmission + +There are eight types of FISes each with its specific 8-bit ID and unique header. +FISes vary in size from 1 Dword up to 2049 Dwords. The number of bytes in a +FIS are always a multiple of four so the transport layer has to fill up with zeros if +there are bytes or bits missing for an entire Dword. +The flow control in this case is only to report to the link layer that the data buffers +are close to over- or underflow. Errors detected are supposed to be reported to +the application layer and the detectable errors are: + - Errors from lower layers like 8b/10b disparity error or CRC errors. + - SATA state or protocol errors caused by standard violation. + - Frame errors like malformed header. + - Internal transport layer errors like buffer overflow. + +Errors are handled in different ways, for example are resending of complete FISes +supported for all kind of FISes besides the data FISes (and the BIST FIS which +is used typically during testing), because that would need buffers in size of 8192 +bytes (maximum supported FIS size). The max sized non-data FIS is 28 bytes so +the costs of a large buffer can be spared. + +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_. + +.. _Thesis: http://www.diva-portal.org/smash/get/diva2:207798/FULLTEXT01.pdf diff --git a/doc/source/docs/specification/oob_sequence.png b/doc/source/docs/specification/oob_sequence.png new file mode 100644 index 00000000..8edacede Binary files /dev/null and b/doc/source/docs/specification/oob_sequence.png differ diff --git a/doc/source/docs/specification/oob_signals.png b/doc/source/docs/specification/oob_signals.png new file mode 100644 index 00000000..9fd831b6 Binary files /dev/null and b/doc/source/docs/specification/oob_signals.png differ diff --git a/doc/source/docs/specification/sata_layers.png b/doc/source/docs/specification/sata_layers.png new file mode 100644 index 00000000..5b5cdead Binary files /dev/null and b/doc/source/docs/specification/sata_layers.png differ diff --git a/doc/source/docs/specification/scrambler.png b/doc/source/docs/specification/scrambler.png new file mode 100644 index 00000000..6139f28d Binary files /dev/null and b/doc/source/docs/specification/scrambler.png differ 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