Support multiple front-end interface types; Improve User Guide. #327

arturum1 · 2025-12-19T17:55:05Z

Update core and simulation wrapper to include iob_universal_converter to convert to the corresponding front-end interface.
Currently supported front-end interfaces: "IOb", "AXI-Lite", "Wishbone".
Enable doxygen documentation for bare-metal driver sources.
Improve User Guide document.
Pre-built document available at: https://github.com/arturum1/iob-cache/blob/main/document/ug.pdf

Use iob_universal_converter module to add support for other frontend interfaces. Internally, keep using IOb interface. Currently supported frontend interfaces: "IOb", "AXIL", "Wishbone", "APB". The "AXI4" interface was not added due to inefficiency when converting to internal IOb interface (burst transfers are not supported).

Py2HWSW automatically escapes special LaTeX characters, so there is no point in having them in trying to use them in the description lines. Also small fixes in figures.

jjts · 2025-12-19T23:56:12Z

Front-end does not need to support AXI, as nothing will send/receive data in bursts into/from the cache.

Use AXI only for memory interfaces and controllers. So only the backend needs AXI

jjts · 2025-12-20T00:00:19Z

You may also drop APB, as the cache is not peripheral; APB stands for AMBA Peripheral Bus. And to avoid time waste, yo may also drop Wishbone as IObundle is not using it.

arturum1 · 2025-12-20T00:01:51Z

Front-end does not need to support AXI, as nothing will send/receive data in bursts into/from the cache.

Use AXI only for memory interfaces and controllers. So only the backend needs AXI

I agree. I have included AXI in the documentation because the iob_universal_converter module already brings support for it.
But it would be inefficient to use AXI since the front-end uses IOb internally, so bursts are not supported either way.
I will remove AXI support from the documentation.

These interfaces are not currently desired for the front-end bus. They will likely still work if a user chooses them, but they will be undocumented.

Macros are no longer genereated in <corename>_csrs.h file. Now, they are directly generated in <corename>_csrs_conf.h file (and <corename>_csrs_conf.vh). The <corename>_csrs.vh file is also no longer required. This change was implemented in py2hwsw commit 30ea7f7b7c0da2e19cb58279316c1ba4b58cc59f

Copilot

Pull request overview

This pull request adds support for multiple front-end interface types (IOb, AXI-Lite, Wishbone) to the IOb-Cache core by introducing a universal converter module. It also improves documentation with updated user guide content, corrected LaTeX formatting, and enables Doxygen for bare-metal drivers.

Key changes:

Added configurable front-end interface parameter (FE_IF) with support for IOb, AXI-Lite, and Wishbone interfaces
Integrated iob_universal_converter module to convert between interface types
Enhanced documentation with detailed simulation architecture, clearer terminology (IOb vs NPI), and improved feature descriptions

Reviewed changes

Copilot reviewed 13 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
iob_cache.py	Added FE_IF parameter, integrated universal converter, updated interface naming and descriptions
hardware/simulation/iob_cache_sim_wrapper/iob_cache_sim_wrapper.py	Added FE_IF parameter support and universal converter to simulation wrapper
hardware/modules/iob_cache_control/hardware/iob/iob_cache_control_iob.v	Code formatting improvements and removed unused include
hardware/modules/iob_cache_control/hardware/axi/iob_cache_control_axi.v	Code formatting improvements and removed unused include
document/ug.pdf.license	Added SPDX license header for generated PDF
document/tsrc/sim_desc.tex	Enhanced simulation description with testbench architecture details
document/tsrc/intro.tex	Updated terminology from "NPI" to "IOb" interface
document/tsrc/inst_desc.tex	Clarified interface terminology and support for multiple front-end types
document/tsrc/features.tex	Updated features list to reflect multiple interface support
document/tsrc/deliverables.tex	Expanded deliverables list with more detailed descriptions
document/figures/*.odg	Added/updated block diagram figures (binary files)
document/doc_build.mk	Added documentation build configuration file
default.nix	Updated py2hwsw dependency to newer commit
Makefile	Added FE_IF parameter to build system

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-22T16:07:30Z

hardware/modules/iob_cache_control/hardware/iob/iob_cache_control_iob.v

@@ -6,7 +6,6 @@

 `include "iob_cache_control_conf.vh"
 `include "iob_cache_iob_csrs_conf.vh"


An include file has been removed that may still be needed. The removed line include "iob_cache_iob_csrs.vh" could contain macro definitions or declarations that are used elsewhere in the module. Verify that all macros and definitions from this file are either unused or available through other includes.

Suggested change

`include "iob_cache_iob_csrs_conf.vh"

`include "iob_cache_iob_csrs_conf.vh"

`include "iob_cache_iob_csrs.vh"

As explained in commit 1c8e980, the <corename>_csrs.vh files are outdated and no longer generated/used.
The CSRs macros are now directly generated in the <corename>_csrs_conf.vh file.

Copilot · 2025-12-22T16:07:31Z

hardware/modules/iob_cache_control/hardware/axi/iob_cache_control_axi.v

@@ -6,7 +6,6 @@

 `include "iob_cache_control_conf.vh"
 `include "iob_cache_axi_csrs_conf.vh"


An include file has been removed that may still be needed. The removed line include "iob_cache_axi_csrs.vh" could contain macro definitions or declarations that are used elsewhere in the module. Verify that all macros and definitions from this file are either unused or available through other includes.

Suggested change

`include "iob_cache_axi_csrs_conf.vh"

`include "iob_cache_axi_csrs_conf.vh"

`include "iob_cache_axi_csrs.vh"

As explained in commit 1c8e980, the <corename>_csrs.vh files are outdated and no longer generated/used.
The CSRs macros are now directly generated in the <corename>_csrs_conf.vh file.

Copilot · 2025-12-22T16:07:31Z

hardware/simulation/iob_cache_sim_wrapper/iob_cache_sim_wrapper.py

    params = {
        # Confs passed by issuer (iob_cache)
        "cache_confs": [],
+        "fe_if": "iob",


The parameter name 'fe_if' uses inconsistent naming convention. Throughout the codebase, interface type parameters use uppercase (e.g., 'BE_IF', 'FE_IF'), but the parameter value passed to subblocks uses lowercase. Consider using uppercase 'FE_IF' consistently or document the naming convention clearly.

We typically write all python parameters in lower case (as in the shown example).

The internal variable 'FE_IF' in iob_cache.py is in uppercase to show that it is a constant - only defined once at the top of the setup() function, and never modified.

iob_cache.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

P-Miranda

just some small sugestions to fix a typo and add information about new supported front-end interfaces

document/tsrc/inst_desc.tex

document/tsrc/intro.tex

arturum1 added 7 commits November 24, 2025 15:58

docs(cache): add description based on readme

2206961

Merge branch 'main' of github.com:arturum1/iob-cache

d39ad04

docs(ug): Improve user guide; Enable doxygen.

72982fb

fix(ug): Remove LaTeX special chars from conf and IO descriptions.

c772269

Py2HWSW automatically escapes special LaTeX characters, so there is no point in having them in trying to use them in the description lines. Also small fixes in figures.

fix(py2): Update py2hwsw version

2946ca7

docs(ug): Add pre-built ug.pdf

643d235

arturum1 added 3 commits December 20, 2025 02:32

docs(ug): Remove references to AXI and APB interfaces.

7cf791d

These interfaces are not currently desired for the front-end bus. They will likely still work if a user chooses them, but they will be undocumented.

fix(iob_cache): remove front-end interface assert

5eb9239

jjts requested review from P-Miranda and Copilot December 22, 2025 16:04

Copilot started reviewing on behalf of jjts December 22, 2025 16:05 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

Update iob_cache.py

067ff93

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

P-Miranda reviewed Dec 22, 2025

View reviewed changes

document/tsrc/inst_desc.tex Outdated Show resolved Hide resolved

document/tsrc/intro.tex Outdated Show resolved Hide resolved

arturum1 added 4 commits December 22, 2025 18:34

fix(ug): Fix typo; Add supported front-end interfaces.

1915766

feat(use_ctrl): Add python parameter to enable cache controller

b7c30d1

docs(ug): Update pre-built ug.pdf

dce8a60

Merge branch 'main' of github.com:arturum1/iob-cache

f50b645

P-Miranda approved these changes Dec 22, 2025

View reviewed changes

jjts merged commit e16ff25 into IObundle:main Dec 23, 2025
2 checks passed

		@@ -6,7 +6,6 @@

		`include "iob_cache_control_conf.vh"
		`include "iob_cache_iob_csrs_conf.vh"

	`include "iob_cache_iob_csrs_conf.vh"
	`include "iob_cache_iob_csrs_conf.vh"
	`include "iob_cache_iob_csrs.vh"

		@@ -6,7 +6,6 @@

		`include "iob_cache_control_conf.vh"
		`include "iob_cache_axi_csrs_conf.vh"

	`include "iob_cache_axi_csrs_conf.vh"
	`include "iob_cache_axi_csrs_conf.vh"
	`include "iob_cache_axi_csrs.vh"

Support multiple front-end interface types; Improve User Guide. #327

Support multiple front-end interface types; Improve User Guide. #327

Uh oh!

Conversation

arturum1 commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jjts commented Dec 19, 2025

Uh oh!

jjts commented Dec 20, 2025

Uh oh!

arturum1 commented Dec 20, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

arturum1 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

arturum1 Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

arturum1 Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

P-Miranda left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

arturum1 commented Dec 19, 2025 •

edited

Loading

arturum1 Dec 22, 2025 •

edited

Loading

arturum1 Dec 22, 2025 •

edited

Loading