Subversion Repositories neorv32

<<<
:sectnums:
==== Internal Bus Monitor (BUSKEEPER)

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source file(s): | neorv32_buskeeper.vhd | 
| Software driver file(s): | none | 
| Top entity port:         | none | 
| Configuration generics:  | none | 
| Package constants:       | `max_proc_int_response_time_c` | Access time window (#cycles)
| CPU interrupts:          | none | 
|=======================


**Theory of Operation**

The Bus Keeper is a fundamental component of the processor's internal bus system that ensures correct bus operations
to maintain execution safety. The Bus Keeper monitors every single bus transactions that is intimated by the CPU.
If an accessed device responds with an error condition or do not respond within a specific _access time window_,
the according bus access fault exception is raised. The following exceptions can be raised by the Bus Keeper
(see section <<_neorv32_trap_listing>> for all CPU exceptions):

* `TRAP_CODE_I_ACCESS`: error during instruction fetch bus access
* `TRAP_CODE_S_ACCESS`: error during data store bus access
* `TRAP_CODE_L_ACCESS`: error during data load bus access

The **access time window**, in which an accessed device has to respond, is defined by the `max_proc_int_response_time_c`
constant from the processor's VHDL package file (`rtl/neorv32_package.vhd`). The default value is **15 clock cycles**.

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_ bit defines the type of the bus fault:

* `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`).
* `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>>).

[NOTE]
Bus access fault exceptions are also raised if a physical memory protection (PMP) rule is violated. In this case
the _BUSKEEPER_ERR_FLAG_ bit remains zero (since the error signal is not triggered by the BUSKEEPER but by
the CPU's PMP logic).


**NULL Address Check**

The bus keeper can ensure that no accesses are permitted to NULL addresses (`addr = 0x00000000`). These kind of
access often occur when using uninitialized pointers. If the _BUSKEEPER_NULL_CHECK_EN_ bit is set, any access to
address zero (instruction fetch, load data, store data) will raise an according bus exception. This flag
automatically clears on a hardware reset.

If a NULL address access has been detected the _BUSKEEPER_ERR_FLAG_ flag is set and the _BUSKEEPER_ERR_TYPE_
flag is cleared indicating a "Device Error".

[NOTE]
Address 0 is normally used by the IMEM and contains boot code instructions that are executed _once_ right after
hardware reset. Hence, activating the bus keeper's NULL check in application code will not corrupt code execution
at all.


.BUSKEEPER register map (`struct NEORV32_BUSKEEPER`)
[cols="<2,<2,<4,^1,<4"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
.3+<| `0xffffff7C` .3+<| `NEORV32_BUSKEEPER.CTRL` <|`0`  _BUSKEEPER_ERR_TYPE_      ^| r/- | Bus error type, valid if _BUSKEEPER_ERR_FLAG_
                                                  <|`16` _BUSKEEPER_NULL_CHECK_EN_ ^| r/w <| Enable NULL address check when set
                                                  <|`31` _BUSKEEPER_ERR_FLAG_      ^| r/- <| Sticky error flag, clears after read or write access
|=======================