litesata: add doc for frontend

misoclib/mem/litesata/doc/source/docs/frontend/index.rst

@@ -3,5 +3,91 @@
 ========================
 Frontend
 ========================
-.. note::
-	Please contribute to this document, or support us financially to write it.
+
+Crossbar and user ports
+=======================
+
+LiteSATA provides a crossbar to let the user request the number of port he needs.
+Ports are automatically arbitrated and dispatched to and from the core. In the
+following example we create a core and get a port from the crossbar:
+
+.. code-block:: python
+
+    self.submodules.sata_phy = LiteSATAPHY(platform.device,
+                                           platform.request("sata"),
+                                           "sata_gen2",
+                                           clk_freq)
+    self.submodules.sata = LiteSATA(self.sata_phy)
+    user_port = self.sata.crossbar.get_port()
+
+Our user_port has 2 endpoints:
+
+ - A Sink used to send commands and write data.
+ - A Source used to receive commands acknowledges and receive read data.
+
+Packets description
+===================
+
+Sink and Source are packets with additional parameters. A packet has the following signals:
+
+ - stb: Strobe signal indicates that command or data is valid.
+ - sop: Start Of Packet signal indicates that current command or data is the first of the packet.
+ - eop: End Of Packet signal indicates that current command or data is the last of the packet.
+ - ack: Response from the endpoint indicates that core is able to accept our command or data.
+ - data: Current data of the packet.
+
+.. figure:: packets.png
+   :scale: 30 %
+   :align: center
+
+   An example of packet transaction between endpoints.
+
+.. tip::
+
+	- When a packet only has a command or data, sop and eop must be set to 1 on the same clock cycle.
+	- A data is accepted when stb=1 and ack=1.
+
+User Commands
+=============
+
+All HDD transfers are initiated using the Sink endpoint which has the following signals:
+
+ - write: 1 bit signal indicates if we want to write data to the HDD.
+ - read: 1 bit signal indicaties if we want to read data from the HDD.
+ - identify: 1 bit signal indicates if command is an identify device command (use to get HDD informations).
+ - sector: 48 bits signal, the sector number we are going to write or read.
+ - count: 16 bits signal, the number of sectors we are going to write or read.
+ - data: 32 bits signal, the write data.
+
+.. tip::
+
+	- write, read, identify, sector, count are parameters so remain constant for a packet duration.
+	- sector, count are ignored during an identify command.
+	- data is ignored during a read or identify command.
+
+User Responses
+==============
+
+HDD responses are obtained from the Source endpoint which has the following signals:
+
+ - write: 1 bit signal indicates if command was a write.
+ - read: 1 bit signal indicaties if command was a read.
+ - identify: 1 bit signal indicates if command was an identify device command.
+ - last: 1 bit signal indicates if this is the last packet of the response. (A Response can be return in several packets)
+ - failed: 1 bit signal identicates if an error was detected in the response (CRC, FIS...)
+ - data: 32 bits signal, the read data
+
+.. tip::
+
+	- write, read, identify, last are parameters so remain constant for a packet duration.
+	- data can be ignored in the case of a write or identify command.
+	- in case of a read command, read data packets are presented followed by an empty packet indicating the end of the transaction (last=1).
+
+Examples
+========
+
+A BIST_ (Data generator and checker) design is provided. It can be used to understand how to connect
+your logic to the user_port provided by the crossbar. (See LiteSATABISTGenerator, LiteSATABISTChecker and LiteSATABISTIdentify)
+
+.. _BIST: https://github.com/m-labs/misoc/blob/master/misoclib/mem/litesata/frontend/bist.py
+