Merge pull request #244 from stnolting/add_xip_module

✨ Add Execute In Place (XIP) Module

CHANGELOG.md

@@ -26,6 +26,7 @@ defined by the `hw_version_c` constant in the main VHDL package file [`rtl/core/
 
 | Date (*dd.mm.yyyy*) | Version | Comment |
 |:----------:|:-------:|:--------|
+| 02.01.2022 | 1.6.5.3 | :sparkles: **added Execute In Place (XIP) module** allowing code to be directly executed from an external SPI flash, see [PR #244](https://github.com/stnolting/neorv32/pull/244) |
 | 02.01.2022 | 1.6.5.2 | :bug: fixed minor bug in CPU's instruction fetch unit (only issue new instruction fetch request when the previous one has been completed) |
 | 16.12.2021 |[**:rocket:1.6.5**](https://github.com/stnolting/neorv32/releases/tag/v1.6.5) | **New release** |
 | 15.12.2021 | 1.6.4.10 | minor logic optimization of CPU's pipeline front-end (instruction fetch and instruction issue) |

README.md

@@ -126,6 +126,7 @@ for tightly-coupled custom co-processor extensions
 
 **Advanced**
 
+* execute in place module ([XIP](https://stnolting.github.io/neorv32/#_execute_in_place_module_xip)) to directly execute code from SPI flash
 * _true random_ number generator ([TRNG](https://stnolting.github.io/neorv32/#_true_random_number_generator_trng))
 * on-chip debugger ([OCD](https://stnolting.github.io/neorv32/#_on_chip_debugger_ocd)) accessible via JTAG interface - implementing
 the [*Minimal RISC-V Debug Specification Version 0.13.2*](https://github.com/riscv/riscv-debug-spec)

docs/datasheet/cpu.adoc

@@ -260,7 +260,7 @@ RISC-V compatibility.
 
 .Physical Memory Protection
 [IMPORTANT]
-The physical memory protection (see section <<_machine_physical_memory_protection>>)
+The physical memory protection (see section <<_machine_physical_memory_protection_csrs>>)
 only supports the modes _OFF_ and _NAPOT_ yet and a minimal granularity of 8 bytes per region.
 
 .Atomic Memory Operations
@@ -699,7 +699,7 @@ In this case the following additional CSRs are available:
 * `pmpaddr*` (0..63, depending on configuration): PMP address registers
 
 [TIP]
-See section <<_machine_physical_memory_protection>> for more information regarding the PMP CSRs.
+See section <<_machine_physical_memory_protection_csrs>> for more information regarding the PMP CSRs.
 
 The actual number of regions and the minimal region granularity are defined via the top entity
 `PMP_MIN_GRANULARITY` and `PMP_NUM_REGIONS` generics. `PMP_MIN_GRANULARITY` defines the minimal available

docs/datasheet/overview.adoc

@@ -135,6 +135,7 @@ devices. Precise exceptions allow a defined and fully-synchronized state of the
 ** optional general purpose IO and PWM and native NeoPixel (c) compatible smart LED interface
 ** optional embedded memories / caches for data, instructions and bootloader
 ** optional external memory interface (Wishbone / AXI4-Lite) and stream link interface (AXI4-Stream) for custom connectivity
+** optional execute in place (XIP) module
 ** on-chip debugger compatible with OpenOCD and gdb
 * **Software framework**
 ** GCC-based toolchain - prebuilt toolchains available; application compilation based on GNU makefiles
@@ -248,6 +249,7 @@ neorv32_top.vhd                  - NEORV32 Processor top entity
 ├neorv32_uart.vhd                - Universal async. receiver/transmitter
 ├neorv32_wdt.vhd                 - Watchdog timer
 ├neorv32_wishbone.vhd            - External (Wishbone) bus interface
+├neorv32_xip.vhd                 - Execute in place module
 ├neorv32_xirq.vhd                - External interrupt controller
 │
 ├mem/neorv32_dmem.default.vhd    - _Default_ data memory (architecture-only)
@@ -323,7 +325,7 @@ https://stnolting.github.io/neorv32/ug/#_application_specific_processor_configur
 | Module        | Description                                           | LEs | FFs | MEM bits | DSPs
 | Boot ROM      | Bootloader ROM (4kB)                                  |   2 |   1 |    32768 |    0
 | **BUSKEEPER** | Processor-internal bus monitor                        |   9 |   6 |        0 |    0
-| **BUSSWITCH** | Bus mux for CPU instr. and data interface             |  63 |   8 |        0 |    0
+| **BUSSWITCH** | Bus multiplexer for CPU instr. and data interface     |  63 |   8 |        0 |    0
 | CFS           | Custom functions subsystemfootnote:[Resource utilization depends on actually implemented custom functionality.] | - | - | - | -
 | DMEM          | Processor-internal data memory (8kB)                  |  19 |   2 |    65536 |    0
 | DM            | On-chip debugger - debug module                       | 493 | 240 |        0 |    0
@@ -344,6 +346,7 @@ https://stnolting.github.io/neorv32/ug/#_application_specific_processor_configur
 | WISHBONE      | External memory interface                             | 114 | 110 |        0 |    0
 | XIRQ          | External interrupt controller (32 channels)           | 241 | 201 |        0 |    0
 | GPTMR         | General Purpose Timer                                 | 153 | 107 |        0 |    0
+| XIP           | Execute in place module                               | 344 | 269 |        0 |    0
 |=======================
 
 

docs/datasheet/soc.adoc

@@ -26,6 +26,7 @@ image::neorv32_processor.png[align=center]
 * _optional_ NeoPixel(TM)/WS2812-compatible smart LED interface (<<_smart_led_interface_neoled,**NEOLED**>>)
 * _optional_ external interrupt controller with up to 32 channels (<<_external_interrupt_controller_xirq,**XIRQ**>>)
 * _optional_ general purpose 32-bit timer (<<_general_purpose_timer_gptmr,**GPTMR**>>)
+* _optional_ execute in place module (<<_execute_in_place_module_xip,**XIP**>>)
 * _optional_ on-chip debugger with JTAG TAP (<<_on_chip_debugger_ocd,**OCD**>>)
 * bus keeper to monitor processor-internal bus transactions (<<_internal_bus_monitor_buskeeper,**BUSKEEPER**>>)
 * system configuration information memory to check HW configuration via software (<<_system_configuration_information_memory_sysinfo,**SYSINFO**>>)
@@ -82,6 +83,11 @@ bits/channels are hardwired to zero.
 4+^| **Advanced Memory Control Signals**
 | `fence_o`  | 1 | out | indicates an executed _fence_ instruction
 | `fencei_o` | 1 | out | indicates an executed _fencei_ instruction
+4+^| **Execute In Place Interface (<<_execute_in_place_module_xip,**XIP**>>)**
+| `xip_csn_o` | 1 | out | chi select, low-active
+| `xip_clk_o` | 1 | out | serial clock
+| `xip_sdi_i` | 1 | in  | serial data input
+| `xip_sdo_o` | 1 | out | serial data output
 4+^| **Stream Link Interface (<<_stream_link_interface_slink,SLINK>>)**
 | `slink_tx_dat_o` | 8x32 | out | TX link _n_ data
 | `slink_tx_val_o` |    8 | out | TX link _n_ data valid
@@ -434,7 +440,7 @@ shift-related operations of the <<_b_bit_manipulation_operations>> extension.**
 |======
 | **CPU_CNT_WIDTH** | _natural_ | 64
 3+| This generic configures the total size of the CPU's `[m]cycle` and `[m]instret` CSRs (low word + high word).
-The maximum value is 64, the minimum value is 0. See section <<_machine_counters_and_timers>> for more information.
+The maximum value is 64, the minimum value is 0. See section <<_machine_counter_and_timer_csrs>> for more information.
 This generic is only relevant if the `Zicntr` ISa extension is enabled (<<_cpu_extension_riscv_zicntr>>).
 Note: configurations with <<_cpu_cnt_width>> less than 64 bits do not comply to the RISC-V specs.
 |======
@@ -595,14 +601,14 @@ and instruction memories there is not point of implementing the i-cache.
 
 
 :sectnums!:
-===== _ICACHE_NUM_BLOCK_
+===== _ICACHE_NUM_BLOCKS_
 
 [cols="4,4,2"]
 [frame="all",grid="none"]
 |======
 | **ICACHE_NUM_BLOCKS** | _natural_ | 4
 3+| Number of blocks (cache "pages" or "lines") in the instruction cache. Has to be a power of two. Has no
-effect when <<_icache_dmem_en>> is false.
+effect when <<_icache_en>> is false.
 |======
 
 
@@ -614,7 +620,7 @@ effect when <<_icache_dmem_en>> is false.
 |======
 | **ICACHE_BLOCK_SIZE** | _natural_ | 64
 3+| Size in bytes of each block in the instruction cache. Has to be a power of two. Has no effect when
-<<_icache_dmem_en>> is _false_.
+<<_icache_en>> is _false_.
 |======
 
 
@@ -626,7 +632,7 @@ effect when <<_icache_dmem_en>> is false.
 |======
 | **ICACHE_ASSOCIATIVITY** | _natural_ | 1
 3+| Associativity (= number of sets) of the instruction cache. Has to be a power of two. Allowed configurations:
-`1` = 1 set, direct mapped; `2` = 2-way set-associative. Has no effect when <<_icache_dmem_en>> is _false_.
+`1` = 1 set, direct mapped; `2` = 2-way set-associative. Has no effect when <<_icache_en>> is _false_.
 |======
 
 
@@ -1038,6 +1044,18 @@ See section <<_general_purpose_timer_gptmr>> for more information.
 |======
 
 
+:sectnums!:
+===== _IO_XIP_EN_
+
+[cols="4,4,2"]
+[frame="all",grid="none"]
+|======
+| **IO_XIP_EN** | _boolean_ | false
+3+| Implement the execute in place module (XIP) when _true_.
+See section <<_execute_in_place_module_xip>> for more information.
+|======
+
+
 
 <<<
 // ####################################################################################################################
@@ -1176,7 +1194,7 @@ Please note that all processor-internal components including the peripheral/IO d
 accessed from programs running in less-privileged user mode. For example, if the system relies on
 a periodic interrupt from the _MTIME_ timer unit, user-level programs could alter the _MTIME_
 configuration corrupting this interrupt. This kind of security issues can be compensated using the
-PMP system (see <<_machine_physical_memory_protection>>).
+PMP system (see <<_machine_physical_memory_protection_csrs>>).
 
 
 :sectnums:
@@ -1230,7 +1248,7 @@ and byte (not for instruction fetch) quantities (requiring an accordingly aligne
 [TIP]
 The following table shows the _default hardware-defined_ physical memory attributes of each main address space region.
 Additional user-defined attributes (for example certain read/write/execute rights for specific address space regions) can be
-provided using the RISC-V <<_machine_physical_memory_protection>>.
+provided using the RISC-V <<_machine_physical_memory_protection_csrs>>.
 
 [cols="^1,^2,^2,^3,^2"]
 [options="header",grid="rows"]
@@ -1289,7 +1307,11 @@ via the processor's bus interface to external components:
 
 * access to the processor-internal IMEM and processor-internal IMEM is implemented
 * access to the processor-internal DMEM and processor-internal DMEM is implemented
-* access to the bootloader ROM and beyond → addresses >= _BOOTROM_BASE_ (default 0xFFFF0000) will never be forwarded to the external memory interface
+* access to the bootloader ROM and beyond -> addresses >= _BOOTROM_BASE_ (default 0xFFFF0000) will never be forwarded to the external memory interface
+
+[NOTE]
+If the Execute In Place module (XIP) is implemented accesses map to this module are not forwarded to the
+external memory interface. See section <<_execute_in_place_module_xip>> for more information.
 
 If no (or not all) processor-internal memories are implemented, the according base addresses are mapped to external memories.
 For example, if the processor-internal IMEM is not implemented (<<_mem_int_imem_en>> = _false_), the processor will forward
@@ -1517,4 +1539,6 @@ include::soc_xirq.adoc[]
 
 include::soc_gptmr.adoc[]
 
+include::soc_xip.adoc[]
+
 include::soc_sysinfo.adoc[]

docs/datasheet/soc_buskeeper.adoc

@@ -32,13 +32,15 @@ constant from the processor's VHDL package file (`rtl/neorv32_package.vhd`). The
 In case of a bus access fault exception application software can evaluate the Bus Keeper's control register
 `NEORV32_BUSKEEPER.CTRL` to retrieve further details of the bus exception. The _BUSKEEPER_ERR_FLAG_ bit indicates
 that an actual bus access fault has occurred. The bit is sticky once set and is automatically cleared when reading or
-writing the `NEORV32_BUSKEEPER.CTRL` register. The _BUSKEEPER_ERR_TYPE_ indicated the tape of the bus fault:
+writing the `NEORV32_BUSKEEPER.CTRL` register. The _BUSKEEPER_ERR_TYPE_ bits indicate the tape of the bus fault:
 
-* _BUSKEEPER_ERR_TYPE_ = `0` - "Device Error": The bus access exception was cause by the memory-mapped device that
+* _BUSKEEPER_ERR_TYPE_ = 0 - "Device Error": The bus access exception was cause by the memory-mapped device that
 has been accessed (the device asserted it's `err_o`).
-* _BUSKEEPER_ERR_TYPE_ = `1` - "Timeout Error": The bus access exception was caused by the Bus Keeper because the
+* _BUSKEEPER_ERR_TYPE_ = 1 - "Timeout Error": The bus access exception was caused by the Bus Keeper because the
 accessed memory-mapped device did not respond within the access time window. Note that this error type can also be raised
 by the optional timeout feature of the <<_processor_external_memory_interface_wishbone_axi4_lite>>).
+* _BUSKEEPER_ERR_TYPE_ = 2 - "Unexpected ACK": There was an ACK signal received while there was no pending transfer.
+* _BUSKEEPER_ERR_TYPE_ = 3 - "Unexpected ERR": There was an ERR signal received while there was no pending transfer.
 
 [NOTE]
 Bus access fault exceptions are also raised if a physical memory protection rule is violated. In this case
@@ -50,6 +52,7 @@ the _BUSKEEPER_ERR_FLAG_ bit remains zero.
 [options="header",grid="all"]
 |=======================
 | Address | Name [C] | Bit(s), Name [C] | R/W | Function
-.2+<| `0xffffff7C` .2+<| `NEORV32_BUSKEEPER.CTRL` <|`0`  _BUSKEEPER_ERR_TYPE_ ^| r/- <| Bus error type, valid if _BUSKEEPER_ERR_FLAG_ is set: `0`=device error, `1`=access timeout
-                                                  <|`31` _BUSKEEPER_ERR_FLAG_ ^| r/- <| Sticky error flag, clears after read or write access
+.3+<| `0xffffff7C` .3+<| `NEORV32_BUSKEEPER.CTRL` <|`0`  _BUSKEEPER_ERR_TYPE_LSB_ ^| r/- .8+<| Bus error type, valid if _BUSKEEPER_ERR_FLAG_ is set: 0=device error, 1=access timeout, 2=unexpected ACK, 3=unexpected ERR
+                                                  <|`1`  _BUSKEEPER_ERR_TYPE_MSB_ ^| r/- 
+                                                  <|`31` _BUSKEEPER_ERR_FLAG_     ^| r/- <| Sticky error flag, clears after read or write access
 |=======================

docs/datasheet/soc_sysinfo.adoc

@@ -50,9 +50,9 @@ and default clock speed) for correct operation.
 | `5`  | _SYSINFO_CPU_ZFINX_     | `Zfinx` extension (`F` sub-/alternative-extension) available when set (via top's <<_cpu_extension_riscv_zfinx>> generic)
 | `6`  | _SYSINFO_CPU_ZXSCNT_    | Custom extension - _Small_ CPU counters: `[m]cycle` & `[m]instret` CSRs have less than 64-bit when set (via top's <<_cpu_cnt_width>> generic)
 | `7`  | _SYSINFO_CPU_ZXNOCNT_   | Custom extension - _NO_ CPU counters: `[m]cycle` & `[m]instret` CSRs are NOT available at all when set (via top's <<_cpu_cnt_width>> generic)
-| `8`  | _SYSINFO_CPU_PMP_       | `PMP` (physical memory protection) extension available when set (via top's <<_>> generic)
-| `9`  | _SYSINFO_CPU_HPM_       | `HPM` (hardware performance monitors) extension available when set (via top's <<_>> generic)
-| `10` | _SYSINFO_CPU_DEBUGMODE_ | RISC-V CPU `debug_mode` available when set (via top's <<_>> generic)
+| `8`  | _SYSINFO_CPU_PMP_       | `PMP` (physical memory protection) extension available when set (via top's <<_pmp_num_regions>> generic)
+| `9`  | _SYSINFO_CPU_HPM_       | `HPM` (hardware performance monitors) extension available when set (via top's <<_cpu_extension_riscv_zihpm>> generic)
+| `10` | _SYSINFO_CPU_DEBUGMODE_ | RISC-V CPU `debug_mode` available when set (via top's <<_on_chip_debugger_en>> generic)
 | `30  | _SYSINFO_CPU_FASTMUL_   | fast multiplication available when set (via top's <<_fast_mul_en>> generic)
 | `31` | _SYSINFO_CPU_FASTSHIFT_ | fast shifts available when set (via top's <<_fast_shift_en>> generic)
 |=======================
@@ -79,13 +79,16 @@ and default clock speed) for correct operation.
 | `18` | _SYSINFO_SOC_IO_UART0_         | set if the primary UART0 is implemented (via top's <<_io_uart0_en>> generic)
 | `19` | _SYSINFO_SOC_IO_SPI_           | set if the SPI is implemented (via top's <<_io_spi_en>> generic)
 | `20` | _SYSINFO_SOC_IO_TWI_           | set if the TWI is implemented (via top's <<_io_twi_en>> generic)
-| `21` | _SYSINFO_SOC_IO_PWM_           | set if the PWM is implemented (via top's <<_io_pwm_en>> generic)
+| `21` | _SYSINFO_SOC_IO_PWM_           | set if the PWM is implemented (via top's <<_io_pwm_num_ch>> generic)
 | `22` | _SYSINFO_SOC_IO_WDT_           | set if the WDT is implemented (via top's <<_io_wdt_en>> generic)
 | `23` | _SYSINFO_SOC_IO_CFS_           | set if the custom functions subsystem is implemented (via top's <<_io_cfs_en>> generic)
 | `24` | _SYSINFO_SOC_IO_TRNG_          | set if the TRNG is implemented (via top's _IO_TRNG_EN_ generic)
 | `25` | _SYSINFO_SOC_IO_SLINK_         | set if the SLINK is implemented (via top's <<_slink_num_tx>> and/or <<_slink_num_rx>> generics)
 | `26` | _SYSINFO_SOC_IO_UART1_         | set if the secondary UART1 is implemented (via top's <<_io_uart1_en>> generic)
 | `27` | _SYSINFO_SOC_IO_NEOLED_        | set if the NEOLED is implemented (via top's <<_io_neoled_en>> generic)
+| `28` | _SYSINFO_SOC_IO_XIRQ_          | set if the XIRQ is implemented (via top's <<_xirq_num_ch>> generic)
+| `29` | _SYSINFO_SOC_IO_GPTMR_         | set if the GPTMR is implemented (via top's <<_io_gptmr_en>> generic)
+| `30` | _SYSINFO_SOC_IO_XIP_           | set if the XIP module is implemented (via top's <<_io_xip_en>> generic)
 |=======================
 
 

docs/datasheet/soc_wishbone.adoc

@@ -42,6 +42,10 @@ access is delegated to the external bus interface if...
 . **and** it does not target the internal bootloader ROM or any of the IO devices - regardless if one or more of these components are
 actually implemented or not.
 
+[NOTE]
+If the Execute In Place module (XIP) is implemented accesses map to this module are not forwarded to the
+external memory interface. See section <<_execute_in_place_module_xip>> for more information.
+
 [TIP]
 See section <<_address_space>> for more information.