1.32.2

Summary

Another pretty minor release that addresses some small bugs.

• Update 'FieldNode.is_volatile' property to include 'singlepulse' fields as volatile. #311
• Fix type name normalization to remain consistent when encountering structs with unassigned values. #292

1.32.1

No changes.
Just re-publishing to add pre-built wheels for Linux aarch64

1.32.0

Summary

This is a pretty minor update that addresses issue #302.

• Fixes behavior of RegNode.fields(include_gaps=True) with overlapping fields.
• Add sw_readable_only and sw_writable_only options to RegNode.fields()

Details

In version 1.29, the utility RegNode.fields() introduced a include_gaps option.

A little known feature of SystemRDL is that a register may contain fields that overlap, as long as they do not have conflicting software access policies. Prior to this release, registers with overlapping fields would return nonsensical reserved regions when queried using RegNode.fields(include_gaps=True). This release fixes this behavior.

Since this query is useful when generating packed structures in various languages, it can also be useful to understand these gaps from a software read-only/write-only perspective. This release also introduces two field filtering options: sw_readable_only and sw_writable_only

1.31.0

Summary

Updates:

• Add Node utilities for querying overlapping registers and fields
• Add Node.component_type_name property

Bugs Fixed:

• Fix Node.find_by_path() to allow empty array suffixes

Details

Overlapping reg/field helper utilities

In SystemRDL is allowable to have registers or fields that exist at the same address or bit offset, as long as they do not have conflicting software access modes.
For example:

field {sw = r} ro_field[31:0];
field {sw = w} wo_field[31:0];

To make it easier for exporters to access information about potential overlaps, some additional helper properties have been added:

• FieldNode.has_overlaps
• FieldNode.overlapping_fields
• RegNode.has_overlaps
• RegNode.overlapping_regs

Add Node.component_type_name property

This is a utility property that returns the SystemRDL component type name, such as "reg", "field", "addrmap", etc.
Not particularly exciting, but this can be useful when generating generic error messages to users about Node objects.

1.30.1

Summary

Updates:

• Significant performance improvements to compilation back-end!
• Split RDLWalker into two different variants: RDLSimpleWalker, RDLSteerableWalker
• Promote several more properties to the Node API layer in preparation for deprecating the Node.inst API
• Update FieldNode.implements_storage: All hardware-writable fields that are qualified by we or wel now imply storage.
• ⚠️ Node.inst deprecated from public API. May be removed/changed in the future.
• ⚠️ Removed deprecated RDLCompiler.define_udp() method

Bugs Fixed:

• Fix incorrect type hints for get_property("hdl_path_slice") and get_property("hdl_path_gate_slice")
• Fix importer support for assigning array values to properties. #276

Details

Performance Improvements

We're excited to announce that with this release, the compilation speed of large RDL designs should be much better! Several aspects of the compilation and elaboration back-end were reworked to eliminate several computational hot-spots.

What actually changed?

• Reworked and simplified how parameter references are represented during the compile process. Eliminates the need to perform an expensive deep-copy of expression syntax trees during each instantiation.
• Reworked the implementation of dynamic property assignments to resolve them on-the-fly and do more intelligent piecemeal object copying while resolving these assignments. This eliminates even more copy operations.
• Eliminate expensive deep-copy operations on component members and their children when instantiating. Since this operation was previously done on each instantiation, this represented a very poor performance scaling of approximately O(n^2), where n = the hierarchical depth of the design.
• Optimized internal elaboration instantiation mechanism to eliminate unnecessary string comparisons (Contributed by @nachumg via #290)
• Several other minor hot-path optimizations that added up to a few extra % speedup.

It is difficult to generally quantify the speedup you should expect since it depends on the depth and breadth of your specific design, but for large projects it will definitely be noticeable.

New alternatives to RDLWalker

During our code profiling adventure, we discovered that the additional overhead to implement the seldom-used WalkerAction traversal steering mechanism was somewhat significant. If your application does not require this mechanism when using a Walker/Listener, recommend using a new, more lightweight RDLSimpleWalker.

The old walker has been renamed to RDLSteerableWalker for clarity. To avoid breaking existing libraries, an alias to this via the old name is still provided.

Promote several more properties to the Node API layer

This release adds the following properties and methods to the Node API layer:

• Node.inst_src_ref
• Node.def_src_ref
• Node.property_src_ref
• Node.get_scope_path()
• Node.parameters
• AddressableNode.n_elements
• RegNode.is_msb0_order

Accessing internals via Node.inst is no longer recommended (See deprecation details below). If you are a tool maintainer, strive to clean up any references in your code from Node.inst.<old> to Node.<new>

⚠️ Node.inst deprecated from public API

The Node.inst component layer is now no longer considered part of the public API, and querying into these Component objects is not recommended. This release preserves the interface as much as possible, but beware that this may not be true in future releases.

Originally, interaction with the elaborated register model encouraged accessing some concepts from the Node objects, and others from the Component layer via Node.inst. This split of where to get information added unnecessary complexity to the API, and also created a very large grey area as to what is actually part of the stable & public API. This grey-area makes maintenance difficult since it prevents breaking changes from being made in Component objects. Removing the requirement that the Component layer be part of a stable user-facing API allows the flexibility for implementing future enhancements that require more drastic changes to the internal object model.

In order to prepare for this, more functionality has been promoted into the Node classes so that ideally, developers only need to rely on that layer as the user-facing API.
As mentioned earlier, please strive to strive to clean up any references in your code from Node.inst.<old> to Node.<new>.

⚠️ Removed deprecated RDLCompiler.define_udp() method

This UDP registration method has been deprecated for a few years, since the 1.25.0 release . Finally cleaning up.
If you haven't migrated to the new UDP registration scheme yet, see the details in the docs.

1.30.0 (YANKED)

Note

This release was yanked from pypi due to a regression (SystemRDL/PeakRDL-regblock#162)

1.30.0.rc1

Release Candidate 1 of v1.30.0 to facilitate wider testing.

Request for beta-testers!

The upcoming v1.30.0 release includes some pretty significant internal changes. Although we believe the existing testcases assert that nothing broke, there is always a possibility that something was missed.

Areas to focus on:

• Handling of RDL parameters, and their propagation to assignments
• Dynamic Property Assignments

This will not get pulled by pip automatically, so try the pre-release by installing via:

python3 -m pip install systemrdl-compiler==1.30.0.rc1

... and let me know if something is not working as expected.

1.29.3

Summary

Updates:

• Improve namespace collision errors to also show location of previous definition. #231, #235
• Add option for RegNode.fields() utility to also return gaps between fields. #244
• Node.children(), Node.signals(), Node.registers(), RegNode.fields(), RegNode.aliases(), and FieldNode.aliases() now return lists rather than generators.
• Significant improvements in static type hinting. #242
  • Node iterators now advertise more accurate narrowed return types.
  • Node.parent, Node.inst, and other members are more accurately typed in subclasses
  • Expected return types annotated for all built-in properties from Node.get_property()

Bugs fixed:

• Fix internal error from compiler if parser fails to produce a parse tree. #243
• Move Node.fields() method to be exclusively for RegNode as it is meaningless for all other node types.
• Fix missed elaboration of signal's 'external' property. #245

Details

Better namespace collision errors

Previously, if you had multiple declarations of a component of the same name in the same namespace, the compiler would only report the offending second definition. In large designs, this could result in a lengthy search for what is causing the namespace collision.
This release introduces an additional warning message that provides more context.

RegNode.fields() can now return gaps between fields

RDL has no explicit concept for reserved fields, so historically the RegNode.fields() utility would only return actual existing fields.
For many output generators, calculating the gaps for padding between fields is still a very common operation. Speaking from experience, it is also very easy to screw up!

This update adds an optional argument: RegNode.fields(include_gaps=True).
When enabled, one can iterate over fields, and gaps between fields:

for field in reg_node.fields(include_gaps=True):
    if isinstance(field, FieldNode):
        print(f"Actual field: {field}")
    elif isinstance(field, tuple): # <-- NEW!
        high, low = field
        print(f"Gap between fields: [{high}:{low}]")

Node iterator utilities now return lists instead of generators

The Node.children(), Node.signals(), Node.registers(), RegNode.fields(), RegNode.aliases(), and FieldNode.aliases() utilities used to be implemented as generators.
It turns out that since these are relatively low-cost operations, it is more performant in nearly all cases for the API to directly construct lists instead.
This should have zero impact on your code, except for maybe allowing you to remove a few pesky re-casts to lists in some places.

Significant improvements in static type hinting

If you are a developer, this is a massive quality-of-life improvement.
Nearly all of the public compiler API is now properly type-annotated. Most notably, the Node.get_property() is exhaustively annotated with overload annotations. If you're using VSCode+PyLance, this means you get really nice auto-completion for available property names:

... as well as property-specific return type inlay hints:

(Did you know the "reset" property can return all those other variants? Most people assume it is always an int!)

1.28.0

Updates:

• ⚠️ Drop support for Python 3.5 and 3.6
• C extension reworked to be compatible with the Python Stable ABI. Rather than generating per-python-version wheels, simplified deploy to only produce abi3 wheels.
• Add usedforsecurity flag to all hashlib calls to satisfy FIPS audits (#219)
• Fix missing py.typed from installed package. #207, #241
• Fix comparison of default UDP assignment with API-provided object. #213
• Add __hash__ method for UserEnumMemberContainer. #239
• Fix use of enums in concatenation expressions. #230
• Fix an amusing edge-case that causes an out-of-memory crash. #224

1.27.3

Bug Fixes:

• Fix FieldNode.is_volatile incorrectly returning non-boolean value if some properties are assigned references.