From a9da892b57028aecf2286045926e71de4a193876 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Tue, 26 May 2015 13:54:31 +0800 Subject: [PATCH] litesata: doc fixes --- .../doc/source/docs/frontend/index.rst | 50 +++++++++---------- .../docs/getting_started/bug_reports.rst | 3 +- .../source/docs/getting_started/downloads.rst | 8 +-- .../doc/source/docs/getting_started/index.rst | 5 +- .../mem/litesata/doc/source/docs/index.rst | 36 ------------- .../litesata/doc/source/docs/intro/about.rst | 17 +++---- 6 files changed, 40 insertions(+), 79 deletions(-) delete mode 100644 misoclib/mem/litesata/doc/source/docs/index.rst diff --git a/misoclib/mem/litesata/doc/source/docs/frontend/index.rst b/misoclib/mem/litesata/doc/source/docs/frontend/index.rst index a7bf09e7..bed6eb93 100644 --- a/misoclib/mem/litesata/doc/source/docs/frontend/index.rst +++ b/misoclib/mem/litesata/doc/source/docs/frontend/index.rst @@ -1,8 +1,8 @@ .. _frontend-index: -======================== +=================== Frontend interfaces -======================== +=================== All frontend modules of LiteSATA share the same user interface based on packets. An interface has 2 endpoints: @@ -12,8 +12,8 @@ An interface has 2 endpoints: Packets and user commands/responses are described in the next sections. -Packets description -=================== +Packet description +================== Sink and Source are packets with additional parameters. A packet has the following signals: @@ -39,16 +39,16 @@ User Commands All transfers are initiated using the Sink endpoint which has the following signals: - - :code:`write`: 1 bit signal indicates if we want to write data to the HDD. - - :code:`read`: 1 bit signal indicaties if we want to read data from the HDD. - - :code:`identify`: 1 bit signal indicates if command is an identify device command (use to get HDD informations). + - :code:`write`: 1 bit signal, indicates if we want to write data to the HDD. + - :code:`read`: 1 bit signal, indicaties if we want to read data from the HDD. + - :code:`identify`: 1 bit signal, indicates if the command is an identify device command (use to get HDD information). - :code:`sector`: 48 bits signal, the sector number we are going to write or read. - :code:`count`: 16 bits signal, the number of sectors we are going to write or read. - :code:`data`: n x 32 bits signal, the write data. (n depends of the frontend module) .. tip:: - - :code:`write`, :code:`read`, :code:`identify`, :code:`sector`, :code:`count` are parameters so remain constant for a packet duration. + - :code:`write`, :code:`read`, :code:`identify`, :code:`sector`, :code:`count` are parameters which must remain constant for the duration of the packet. - :code:`sector`, :code:`count` are ignored during an :code:`identify` command. - :code:`data` is ignored during a :code:`read` or :code:`identify` command. @@ -57,32 +57,32 @@ User Responses Responses are obtained from the Source endpoint which has the following signals: - - :code:`write`: 1 bit signal indicates if command was a write. - - :code:`read`: 1 bit signal indicaties if command was a read. - - :code:`identify`: 1 bit signal indicates if command was an identify device command. - - :code:`last`: 1 bit signal indicates if this is the last packet of the response. (A response can be return in several packets) - - :code:`failed`: 1 bit signal identicates if an error was detected in the response (CRC, FIS...) + - :code:`write`: 1 bit signal, indicates if the command was a write. + - :code:`read`: 1 bit signal, indicaties if the command was a read. + - :code:`identify`: 1 bit signal, indicates if the command was an identify device command. + - :code:`last`: 1 bit signal, indicates if this is the last packet of the response. (A response can be return in several packets) + - :code:`failed`: 1 bit signal, indicates if an error was detected in the response (CRC, FIS...) - :code:`data`: n x 32 bits signal, the read data. (n depends of the frontend module) .. tip:: - - :code:`write`, :code:`read`, :code:`identify`, :code:`last` are parameters so remain constant for a packet duration. + - :code:`write`, :code:`read`, :code:`identify`, :code:`last` are parameters that must remain constant for the duration of a packet. - :code:`data` can be ignored in the case of a :code:`write` or :code:`identify` command. - in case of a :code:`read` command, read data packets are presented followed by an empty packet indicating the end of the transaction (last=1). -======================== +================ Frontend modules -======================== +================ LiteSATA provides a configurable and flexible frontend that can be used to: -- Provides any number of user ports. +- Provide any number of user ports. - Generate any RAID configuration when used with multiple HDDs. Crossbar ======== -The crossbar let the user request any number of ports. It automatically arbitrate requests and dispatch responses to the corresponding ports. +The crossbar lets the user request any number of ports. It automatically arbitrates requests and dispatches responses to the corresponding ports. The following example creates a crossbar and 2 user ports: @@ -95,7 +95,7 @@ The following example creates a crossbar and 2 user ports: Striping ======== -The striping module segment data so that data is stored on N different controllers. (RAID0 equivalent) +The striping module segments data so that data is stored on N different controllers (RAID0 equivalent). .. code-block:: python @@ -120,7 +120,7 @@ The following example creates a striping with 2 HDDs: Mirroring ========= -The mirroring module handles N controllers and provides N ports. (RAID1 equivalent) +The mirroring module handles N controllers and provides N ports (RAID1 equivalent). Each port has its dedicated controller for reads: @@ -146,7 +146,7 @@ Characteristics: - total writes throughput = (slowest) :code:`controller`'s throughput - total reads throughput = N x :code:`controller`'s throughput -It can be used for data redundancy and/or to increase total reads speed. +It can be used for data redundancy and/or to increase the total read speed. .. code-block:: python @@ -154,8 +154,8 @@ It can be used for data redundancy and/or to increase total reads speed. :code:`sata_striping`'s ports[0] and ports[1] are the user interfaces. -Modules combinations -==================== +Module combinations +=================== Since all frontend modules share the same interface, it's easy to combine them together. @@ -180,9 +180,9 @@ Since it's probably easier to figure out how to use the frontend modules with re - A BIST_ (Data generator and checker) design that can be used to understand how to connect your logic to the user_port provided by the crossbar. -- A Striping_ design that can be used to understand how to connect couple 4 HDDs together in striping mode and do a BIST it. +- A Striping_ design that can be used to understand how to couple 4 HDDs together in striping mode and do a BIST. -- A Mirroring_ design that can be used to understand how to connect couple 4 HDDs together in Mirroring mode and do a BIST it. +- A Mirroring_ design that can be used to understand how to couple 4 HDDs together in Mirroring mode and do a BIST. .. _BIST: https://github.com/m-labs/misoc/blob/master/misoclib/mem/litesata/example_designs/targets/bist.py diff --git a/misoclib/mem/litesata/doc/source/docs/getting_started/bug_reports.rst b/misoclib/mem/litesata/doc/source/docs/getting_started/bug_reports.rst index dc5b0553..d9dfce0f 100644 --- a/misoclib/mem/litesata/doc/source/docs/getting_started/bug_reports.rst +++ b/misoclib/mem/litesata/doc/source/docs/getting_started/bug_reports.rst @@ -7,5 +7,4 @@ Bug Reporting - 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 +complex and/or you are not sure how to proceed, feel free to discuss it with us. diff --git a/misoclib/mem/litesata/doc/source/docs/getting_started/downloads.rst b/misoclib/mem/litesata/doc/source/docs/getting_started/downloads.rst index a372f8e7..01df477e 100644 --- a/misoclib/mem/litesata/doc/source/docs/getting_started/downloads.rst +++ b/misoclib/mem/litesata/doc/source/docs/getting_started/downloads.rst @@ -1,8 +1,8 @@ .. _sdk-download-and-install: -==================== -Download and install -==================== -Please follow Getting started section of LiteSATA README_. +========================= +Download and installation +========================= +Please follow the "Getting started" section of the LiteSATA README_. .. _README: https://github.com/m-labs/misoc/blob/master/misoclib/mem/litesata/README diff --git a/misoclib/mem/litesata/doc/source/docs/getting_started/index.rst b/misoclib/mem/litesata/doc/source/docs/getting_started/index.rst index 8eb05973..4cfd7384 100644 --- a/misoclib/mem/litesata/doc/source/docs/getting_started/index.rst +++ b/misoclib/mem/litesata/doc/source/docs/getting_started/index.rst @@ -4,9 +4,9 @@ Getting Started =============== -Now you know why LiteSATA is :ref:`core for you `, it's time to *get started*. +Now that you know why LiteSATA is the :ref:`core for you `, it's time to *get started*. -This section provides a walk-through of :ref:`downloading and installing the tools`. +This section explains the procedure for :ref:`downloading and installing the tools`. .. toctree:: :maxdepth: 1 @@ -14,4 +14,3 @@ This section provides a walk-through of :ref:`downloading and installing the too downloads FAQ bug_reports - diff --git a/misoclib/mem/litesata/doc/source/docs/index.rst b/misoclib/mem/litesata/doc/source/docs/index.rst deleted file mode 100644 index 2b09fefc..00000000 --- a/misoclib/mem/litesata/doc/source/docs/index.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _documentation-home: - -======================== -LiteSATA Documentation -======================== - -This comprehensive documentation set contains everything you need to know to use LiteSATA and integrate it in your design. - -**Getting started:** - -- :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:** - -- :ref:`phy-index` describes PHY building blocks. -- :ref:`core-index` describes core building blocks. -- :ref:`frontend-index` describes core building blocks. - -**LiteSATA Verifications:** - -- :ref:`simulation-index` describes provided simulations. -- :ref:`test-index` describes provided tests. - -The full hierarchy of articles, opened to the second level, is shown below. - -.. toctree:: - :maxdepth: 2 - - intro/index - getting_started/index - specification/index - phy/index - core/index - frontend/index - simulation/index diff --git a/misoclib/mem/litesata/doc/source/docs/intro/about.rst b/misoclib/mem/litesata/doc/source/docs/intro/about.rst index 207d9acb..5e858052 100644 --- a/misoclib/mem/litesata/doc/source/docs/intro/about.rst +++ b/misoclib/mem/litesata/doc/source/docs/intro/about.rst @@ -1,18 +1,17 @@ .. _about: -================ +============== About LiteSATA -================ +============== -LiteSATA provides a small footprint and configurable SATA gen1/2/3 core. +LiteSATA provides a small footprint and configurable SATA gen1/2 core. -LiteSATA is part of MiSoC libraries whose aims are to lower entry level of complex FPGA cores by providing simple, elegant and efficient implementations of -components used in today's SoC such as Ethernet, SATA, PCIe, SDRAM Controller... +LiteSATA is part of the MiSoC libraries whose aims are to lower entry level of complex FPGA cores by providing simple, elegant and efficient implementations of components used in modern SoCs such as Ethernet, SATA, PCIe, SDRAM controller... -The core uses simple and specific streaming buses and will provides in the future +The core uses simple and specific streaming buses and will provide 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 +Since Python is used to describe the gateware, the core is highly and easily configurable. The synthetizable BIST can be used as a starting point to integrate SATA in @@ -22,8 +21,8 @@ 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 MiSoC library or can be integrated with your standard -design flow by generating the verilog rtl that you will use as a standard core. +LiteSATA can be used as a Python library or can be integrated with your standard +design flow by generating the Verilog RTL that you will use as a standard core. .. _about-toolchain: -- 2.30.2