Merge pull request #30 from Dasharo/phase5_updates

Phase5 updates

docs/changelog/index.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2023-11-26
+
+* [Reduce numbers of bi-directional lines to minimum](../development/verilog_modules/)
+  (Yosys doesn't like them)
+* Switch to OrangeCrab
+    - [Reason](../explanation/hardware-selection/#update-october-2023)
+    - [Updated building instructions](../tutorials/building/) - actual
+      instructions moved to README in top level repository to avoid duplications
+    - [Modified memory map](../development/soc_fpga_communication/)
+    - [New FPGA utilization numbers](../development/verilog_modules/#top-level)
+* [Instructions for connecting TwPM to mainboard - Protectli VP46xx](../tutorials/mainboard-connection/)
+* [Description of new modules](../development/verilog_modules/) (NEORV32,
+  LiteDRAM, TPM buffer)
+
 ## 2023-07-31
 
 ### Added
@@ -11,17 +25,17 @@
 
 ### Added
 
-* [New Verilog Module specification in Development section](../development/verilog_modules.md#tpm-registers-module),
+* [New Verilog Module specification in Development section](../development/verilog_modules/#tpm-registers-module),
   added graphics and links to modules' code
 * Fixed broken links in changelog (here) and [Development section](../development)
-* [First implementation details documented](../explanation/compliance.md)
-* [Update statuses on the roadmap](../roadmap/index.md)
+* [First implementation details documented](../explanation/compliance/)
+* [Update statuses on the roadmap](../roadmap/)
 
 ## 2023-04-20
 
 ### Added
 
-* [Hardware requirements in Explanation section](../explanation/index.md)
-* [Hardware selection in Explanation section](../explanation/index.md)
-* [Building TwPM in Tutorials section](../tutorials/building.md)
-* [Verilog Modules specification in Development section](../development/verilog_modules.md)
+* [Hardware requirements in Explanation section](../explanation/)
+* [Hardware selection in Explanation section](../explanation/)
+* [Building TwPM in Tutorials section](../tutorials/building/)
+* [Verilog Modules specification in Development section](../development/verilog_modules/)

docs/development/index.md

@@ -1,9 +1,9 @@
 # Development
 
-This section of docuemntation contains reference material for those interested
+This section of documentation contains reference material for those interested
 in developing and contributing to the TwPM project.
 
 | Document                              | Goal                                                                           |
 |---------------------------------------|--------------------------------------------------------------------------------|
 | [Verilog modules](verilog_modules.md) | Learn the specification of the existing Verilog modules, so you can contribute |
-| [Communication between M4 and FPGA](m4_fpga_communication.md) | Learn how M4 communicates with FPGA in this project    |
+| [Communication between SoC and FPGA](soc_fpga_communication.md) | Learn how SoC communicates with FPGA in this project |

docs/development/m4_fpga_communication.md → docs/development/soc_fpga_communication.md

@@ -1,22 +1,23 @@
-# Communication between M4 and FPGA
+# Communication between SoC and FPGA
 
-This document describes how FPGA and M4 communicate with each other in TwPM
-project for EOS-S3. State presented here is valid for revision **TBD** of top
+This document describes how FPGA and SoC communicate with each other in TwPM
+project for NEORV32. State presented here is valid for release v0.2.0 of top
 module.
 
 ## Memory map
 
 | Address    | Size | Name     | Access |
 |------------|------|----------|--------|
-| 0x40020000 | 4B   | STATUS   | RO     |
-| 0x40020004 | 4B   | OP_TYPE  | RO     |
-| 0x40020008 | 4B   | LOCALITY | RO     |
-| 0x4002000C | 4B   | BUF_SIZE | RO     |
-| 0x40020040 | 4B   | COMPLETE | WO     |
-| 0x40020800 | 2KiB | FPGA_RAM | RW     |
+| 0xF0000000 | 4B   | STATUS   | RO     |
+| 0xF0000004 | 4B   | OP_TYPE  | RO     |
+| 0xF0000008 | 4B   | LOCALITY | RO     |
+| 0xF000000C | 4B   | BUF_SIZE | RO     |
+| 0xF0000040 | 4B   | COMPLETE | WO     |
+| 0xF0000800 | 2KiB | FPGA_RAM | RW     |
 
-Reads from invalid addresses return `0xBADFABAC` (BAD FABric ACcess), writes are
-dropped. Most values are valid only if `exec` bit in `STATUS` register is set.
+Reads from invalid addresses in 0xF0000000-0xF0000FFF range return `0xBADFABAC`
+(BAD FABric ACcess), writes are dropped. Most values are valid only if `exec`
+bit in `STATUS` register is set.
 
 ## Registers
 
@@ -26,14 +27,10 @@ Reserved bits are read as 0. They may change in the future.
 
 ![Layout of STATUS register](/images/reg-status.png)
 
-This register is expected to be informational only, it doesn't provide any
-information that isn't conveyed through other means (interrupts).
-
 * `exec` indicates that MCU is expected to act upon request sent from FPGA,
   specified in `OP_TYPE` register. [Interrupt](#interrupts) is generated when
   this signal gets set by FPGA.
 * `abort` is set when PC aborts command currently being executed by TPM.
-  [Interrupt](#interrupts) is generated when this signal gets set by FPGA.
 * `complete` is a signal sent towards FPGA by writing to `COMPLETE` register.
   The signal is active for a few cycles after write to that register, after that
   is should be automatically set back to 0.
@@ -87,11 +84,12 @@ dropped.
 
 ## Interrupts
 
-TwPM uses two interrupt signals from FPGA towards M4. First one is `exec` which
-signals that there is an operation to be performed by TPM stack, and another one
-tells that the currently running operation is to be aborted.
+TwPM needs to communicate from FPGA towards SoC when there is an operation to be
+performed by TPM stack. This is done through `mext_irq_i`, which is responsible
+for signaling Machine external interrupt (MEI). This signal is level-triggered
+and high-active. MEI has a dedicated value in `mcause`, shared between all
+external interrupts. The exact reason has to be obtained in a platform-specific
+way; in case of TwPM it can be read from `STATUS` register.
 
-Both interrupts arrive to M4 as IRQ 4, and exact reason for interrupt can be
-read from 4-byte `FB_INTR_RAW` register located at address 0x40004884. Bits 0
-and 1 represent `exec` and `abort`, respectively. Interrupts are cleared by
-writing the same bits to register `FB_INTR` located at 0x40004880.
+The interrupt signal remains active until SoC signals completion by performing
+a write to `COMPLETE` register.