[prim,doc] Updated the main documentation for the post primgen world #27422

HU90m · 2025-06-12T08:03:56Z

This updates the documentation to how primitives are expected to be used.

The documentation doesn't cover the temporary use of a partner:prim_tech:all and the virtual prim_pkg. I think the former could potentially be phased out with a commit in this PR removing lines like fileset_partner ? (partner:prim_tech:all). Unless I'm missing something?

As prim_pkg may be hanging around a little longer than we'd like. A paragraph could be added in a follow up PR explaining how to provide your own prim_pkg as a stop gap. Effort would probably be better spent transitioning away from it rather than documenting it, lest it become an immortal temporary solution.

andreaskurth · 2025-06-12T08:58:25Z

Thanks @HU90m! This would address issue #27372, right? (I've just linked that; please unlink if not appropriate.)

SUMMARY.md

Primitives are slightly different to your usual hw blocks. They should probably be given their own higher level heading, like cores have. Also, sorted so that they are in alphabetical order. Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>

The style guide asks that text be one sentence per line, for clearer diffs. Changing this before planned future edits. Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>

This brings the documentation up to date with how primitives now work and are used. Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>

a-will

Just a bunch of nits. Thanks for writing this!

a-will · 2025-06-16T04:14:37Z

hw/ip/prim/README.md

+* Primitives with a single, generic, implementation are normal SystemVerilog modules inside the `hw/ip/prim/rtl` directory.
+  We call these primitives *technology-independent primitives*.
+* Primitives with multiple implementations are called *technology-dependent primitives*.
+  Each implementation has it's own directory within `hw/ip/` with the prefix `prim`, e.g. `hw/ip/prim_generic/` or `hw/ip/prim_xilinx/`.


nit:

Suggested change

Each implementation has it's own directory within `hw/ip/` with the prefix `prim`, e.g. `hw/ip/prim_generic/` or `hw/ip/prim_xilinx/`.

Each implementation has its own directory within `hw/ip/` with the prefix `prim`, e.g. `hw/ip/prim_generic/` or `hw/ip/prim_xilinx/`.

a-will · 2025-06-16T04:15:58Z

hw/ip/prim/README.md

-properties:
+Collections of technology-dependent primitives are called technology libraries.
+The *generic* technology library contains a pure-SystemVerilog implementation of primitives' functionality.
+It's is commonly used for simulations and as functional reference.


nit:

Suggested change

It's is commonly used for simulations and as functional reference.

This library is commonly used for simulations and as functional reference.

a-will · 2025-06-16T04:17:04Z

hw/ip/prim/README.md


-Technology libraries collect implementations of primitives.
+To allow hardware blocks to be generic across implementations of *technology-dependent primitives*, a feature of FuseSoC called *[virtual cores][]* are used.*


nit: feature is singular

Suggested change

To allow hardware blocks to be generic across implementations of *technology-dependent primitives*, a feature of FuseSoC called *[virtual cores][]* are used.*

To allow hardware blocks to be generic across implementations of *technology-dependent primitives*, a feature of FuseSoC called *[virtual cores][]* is used.*

👍, and I think the * at the end should be removed.

a-will · 2025-06-16T04:27:19Z

hw/ip/prim/README.md


-Technology libraries collect implementations of primitives.
+To allow hardware blocks to be generic across implementations of *technology-dependent primitives*, a feature of FuseSoC called *[virtual cores][]* are used.*
+These can be thought of as similar to virtual methods in C++ or SystemVerilog.


Before this line, we might want to describe what it means to a hardware design engineer, hehe. For example...

Suggested change

These can be thought of as similar to virtual methods in C++ or SystemVerilog.

Any implementation of a virtual core must provide the same functionality and interface.

The module name must be the same, and the parameter and port lists must include all the required members of the interface.

For an analog, virtual cores can be thought of as similar to virtual methods in C++ or SystemVerilog.

Maybe 'analogy' or 'analogon'? ('Analog' always feels itchy to the digital designer in me 😉)

a-will · 2025-06-16T04:30:07Z

hw/ip/prim/README.md

-which contains a pure-SystemVerilog implementation of the functionality. This
-library is commonly used for simulations and as functional reference. The
-`generic` technology library is contained in the `hw/ip/prim_generic` directory.
+To find the interface of a given virtual primitive look at it's generic implementation in `hw/prim_generic/`.


nit:

Suggested change

To find the interface of a given virtual primitive look at it's generic implementation in `hw/prim_generic/`.

To find the interface of a given virtual primitive look at its generic implementation in `hw/prim_generic/`.

a-will · 2025-06-16T04:48:29Z

hw/ip/prim/README.md

+
+If you'd like to depend on a specific implementation, you can add the specific implementation's VLNV instead of the virtual VLNV.
+For example, you would depend on `lowrisc:prim_xilinx:prim_fifo_sync` instead of `lowrisc:prim:prim_fifo_sync` if you wanted to forcefully use the Xilinx implementation.
+**This is not recommended.**


nit: Best to provide a reason alongside recommendations.

Suggested change

**This is not recommended.**

Because this method can restrict the flexibility to swap compatible cores, **this is not recommended.**

a-will · 2025-06-16T04:49:39Z

hw/ip/prim/README.md

+You can rely on the generic implementation or even another library's implementation for other primitives.
+
+Technology libraries don't have to live in the OpenTitan repository.
+If they are not in the OpenTitan repository, you need to make sure the path to them is given to FuseSoC with either an additional `--core-root=` argument or set in `fusesoc.conf`.


nit:

Suggested change

If they are not in the OpenTitan repository, you need to make sure the path to them is given to FuseSoC with either an additional `--core-root=` argument or set in `fusesoc.conf`.

If they are not in the OpenTitan repository, you need to make sure the path to them is given to FuseSoC with either an additional `--cores-root=` argument or set in `fusesoc.conf`.

a-will · 2025-06-16T04:50:02Z

hw/ip/prim/README.md

+
+### Selecting a technology library
+
+You can select a technology library one of two ways.


nit:

Suggested change

You can select a technology library one of two ways.

You can select a technology library in one of two ways.

a-will · 2025-06-16T04:50:22Z

hw/ip/prim/README.md

+
+You can select a technology library one of two ways.
+
+If you have your own invokable core which requires a particular primitive, you should add the technology library's VLNV to it's dependencies.


nit:

Suggested change

If you have your own invokable core which requires a particular primitive, you should add the technology library's VLNV to it's dependencies.

If you have your own invokable core which requires a particular primitive, you should add the technology library's VLNV to its dependencies.

a-will · 2025-06-16T04:50:43Z

hw/ip/prim/README.md

+
+If you have your own invokable core which requires a particular primitive, you should add the technology library's VLNV to it's dependencies.
+`hw/top_earlgrey/chip_earlgrey_cw310.core` is an example of an invokable core requiring a particular technology library, namely `lowrisc:prim_xilinx:all`.
+You'll notice this VLNV in it's dependencies.


nit:

Suggested change

You'll notice this VLNV in it's dependencies.

You'll notice this VLNV in its dependencies.

andreaskurth · 2025-06-16T14:38:06Z

hw/ip/prim/README.md

 ```

+Notice that there aren't xilinx specific implementations for all primitives, so the generic implementation is requested.


Suggested change

Notice that there aren't xilinx specific implementations for all primitives, so the generic implementation is requested.

Notice that there aren't Xilinx specific implementations for all primitives, so the generic implementation is requested.

andreaskurth

Couple of comments, but overall LGTM. Thanks @HU90m!

andreaskurth · 2025-06-16T14:45:52Z

hw/ip/prim/README.md

+   Also, edit the description to better describe the specific implementation.
+4. For every primitive implemented by your library:
+   1. Copy across the generic implementation into your library, e.g. `mv hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.
+   2. Make your changes to the implementation without modifying the module ports or removing parameters.


Suggested change

2. Make your changes to the implementation without modifying the module ports or removing parameters.

2. Make your changes to the implementation without modifying the module ports or parameter declarations.

Because I don't think adding parameters would work? And I added "declarations" because otherwise people might be confused that they cannot change parameter values.

Adding parameters can work in specific circumstances (e.g. somewhere defparam is accepted or where you know there is a specific implementation), but most of the time, it doesn't.

andreaskurth · 2025-06-16T14:46:33Z

hw/ip/prim/README.md

+   Change the vendor and name in this file, e.g. `lowrisc:prim_generic` would become `partner:mytech` where your organisation's name can be used in the place of 'partner'.
+   Also, edit the description to better describe the specific implementation.
+4. For every primitive implemented by your library:
+   1. Copy across the generic implementation into your library, e.g. `mv hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.


Suggested change

1. Copy across the generic implementation into your library, e.g. `mv hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.

1. Copy across the generic implementation into your library, e.g. `cp hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.

Unless you've aliased mv to cp? 😉

andreaskurth · 2025-06-16T14:46:46Z

hw/ip/prim/README.md

+4. For every primitive implemented by your library:
+   1. Copy across the generic implementation into your library, e.g. `mv hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.
+   2. Make your changes to the implementation without modifying the module ports or removing parameters.
+   3. Copy the generic primitive's core description into your library, e.g. `mv hw/ip/prim_generic/prim_generic_flop.core hw/ip/prim_mytech/prim_mytech_flop.core`.


Suggested change

3. Copy the generic primitive's core description into your library, e.g. `mv hw/ip/prim_generic/prim_generic_flop.core hw/ip/prim_mytech/prim_mytech_flop.core`.

3. Copy the generic primitive's core description into your library, e.g. `cp hw/ip/prim_generic/prim_generic_flop.core hw/ip/prim_mytech/prim_mytech_flop.core`.

andreaskurth · 2025-06-16T14:52:52Z

hw/ip/prim/README.md

+   4. Edit this copied primitive core file so that it has the new primitive library name, e.g. replacing `lowrisc:prim_generic:flop` with `partner:prim_mytech:flop`.
+   5. Then in the libraries main core file, e.g. `hw/ip/prim_mytech/prim_mytech.core`, replace all instances of the generic implementation with your specific implementation, e.g. replacing `lowrisc:prim_generic:flop` with `partner:prim_mytech:flop` again.
+
+You don't have to have your own implementation for every primitive.


Depending on the use case / requirements of the implementation, there are some requirements on the prim implementation. For example, if you care about security against physical attacks, you need to constrain the tools you're using to not remove a prim_buf. This isn't (and shouldn't be) part of the generic implementation. Should we create an issue to add documentation on this topic?

andreaskurth · 2025-06-16T14:55:09Z

hw/ip/prim/README.md

+```sh
+fusesoc --cores-root=$OT_REPO run \
+    --flag fileset_partner \
+    --mapping partner:prim_mytech:all


Suggested change

--mapping partner:prim_mytech:all

--mapping partner:prim_mytech:all \

HU90m requested review from Razer6, a-will, andreaskurth and meisnere June 12, 2025 08:03

andreaskurth linked an issue Jun 12, 2025 that may be closed by this pull request

[doc] Prim libraries & primgen documentation is outdated #27372

Open

1 task

andreaskurth reviewed Jun 12, 2025

View reviewed changes

SUMMARY.md Show resolved Hide resolved

HU90m force-pushed the prim-docs branch from 2917745 to a2d89eb Compare June 14, 2025 06:23

HU90m added 3 commits June 14, 2025 07:27

[prim,doc] Edited main page to conform to style guide.

5e60c48

The style guide asks that text be one sentence per line, for clearer diffs. Changing this before planned future edits. Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>

[prim,doc] Updated the main documentation for the post primgen world

0188ccb

This brings the documentation up to date with how primitives now work and are used. Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>

HU90m force-pushed the prim-docs branch from a2d89eb to 0188ccb Compare June 14, 2025 06:30

a-will approved these changes Jun 16, 2025

View reviewed changes

andreaskurth reviewed Jun 16, 2025

View reviewed changes

	Each implementation has it's own directory within `hw/ip/` with the prefix `prim`, e.g. `hw/ip/prim_generic/` or `hw/ip/prim_xilinx/`.
	Each implementation has its own directory within `hw/ip/` with the prefix `prim`, e.g. `hw/ip/prim_generic/` or `hw/ip/prim_xilinx/`.

	It's is commonly used for simulations and as functional reference.
	This library is commonly used for simulations and as functional reference.


		Technology libraries collect implementations of primitives.
		To allow hardware blocks to be generic across implementations of technology-dependent primitives, a feature of FuseSoC called [virtual cores][] are used.*

-These can be thought of as similar to virtual methods in C++ or SystemVerilog.
+Any implementation of a virtual core must provide the same functionality and interface.
+The module name must be the same, and the parameter and port lists must include all the required members of the interface.
+For an analog, virtual cores can be thought of as similar to virtual methods in C++ or SystemVerilog.

	To find the interface of a given virtual primitive look at it's generic implementation in `hw/prim_generic/`.
	To find the interface of a given virtual primitive look at its generic implementation in `hw/prim_generic/`.

	This is not recommended.
	Because this method can restrict the flexibility to swap compatible cores, this is not recommended.

	If they are not in the OpenTitan repository, you need to make sure the path to them is given to FuseSoC with either an additional `--core-root=` argument or set in `fusesoc.conf`.
	If they are not in the OpenTitan repository, you need to make sure the path to them is given to FuseSoC with either an additional `--cores-root=` argument or set in `fusesoc.conf`.


		### Selecting a technology library

		You can select a technology library one of two ways.

	You can select a technology library one of two ways.
	You can select a technology library in one of two ways.


		You can select a technology library one of two ways.

		If you have your own invokable core which requires a particular primitive, you should add the technology library's VLNV to it's dependencies.

	You'll notice this VLNV in it's dependencies.
	You'll notice this VLNV in its dependencies.

		```

		Notice that there aren't xilinx specific implementations for all primitives, so the generic implementation is requested.

	2. Make your changes to the implementation without modifying the module ports or removing parameters.
	2. Make your changes to the implementation without modifying the module ports or parameter declarations.

	1. Copy across the generic implementation into your library, e.g. `mv hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.
	1. Copy across the generic implementation into your library, e.g. `cp hw/ip/prim_generic/rtl/prim_flop.sv hw/ip/prim_mytech/rtl/prim_flop.sv`.

	3. Copy the generic primitive's core description into your library, e.g. `mv hw/ip/prim_generic/prim_generic_flop.core hw/ip/prim_mytech/prim_mytech_flop.core`.
	3. Copy the generic primitive's core description into your library, e.g. `cp hw/ip/prim_generic/prim_generic_flop.core hw/ip/prim_mytech/prim_mytech_flop.core`.

	--mapping partner:prim_mytech:all
	--mapping partner:prim_mytech:all \

[prim,doc] Updated the main documentation for the post primgen world #27422

Are you sure you want to change the base?

[prim,doc] Updated the main documentation for the post primgen world #27422

Uh oh!

Conversation

HU90m commented Jun 12, 2025

Uh oh!

andreaskurth commented Jun 12, 2025

Uh oh!

Uh oh!

a-will left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreaskurth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!