========================
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
+
projects / litex.git / commitdiff
