Skip to content

Allow register fields named width, address, debug or access - #1674

Open
0z5a wants to merge 1 commit into
Xilinx:pynq-nextfrom
0z5a:register-field-named-width
Open

0z5a wants to merge 1 commit into
Xilinx:pynq-nextfrom
0z5a:register-field-named-width

Conversation

@0z5a

@0z5a 0z5a commented Nov 19, 2026

Copy link
Copy Markdown

I started from #1480. A scalar HLS argument called width makes register_map fail with RecursionError. HLS IP exposes each scalar argument as a register with one field of the same name. A field becomes a property on the Register subclass, so a field named width replaced the attribute that Register.__init__ sets, and the register called its own field setter while it was being built.

width is not the only name affected. On pynq-next I get this with a single-field register:

Field name Read-write field Read-only field
width RecursionError AttributeError: ... has no setter
address AttributeError: ... no attribute 'width' AttributeError: ... has no setter
access TypeError: '>' not supported between ... 'str' and 'int' AttributeError: ... has no setter
debug AttributeError: ... no attribute '_buffer' AttributeError: ... has no setter
buffer, count works works

All of these fail while the RegisterMap is being built, so the rest of that IP's registers can't be reached either.

The change keeps the register's own state in private attributes (_address, _width, _access, _debug_enabled) and uses those internally, including the sort key in RegisterMap.__repr__. address, width, debug and access stay available as properties with setters on Register, so plain registers and existing code that reads or sets them behave as before. On a register that has a field with one of these names, the name now means the field, which is what the HLS driver in #1480 expects (register_map.width = width).

In #1480 a reserved-name check with a clearer error was suggested. I went with making these names work instead. width is a natural name for an HLS argument (the IP in #1480 has width and height), and with a check that IP would still have no usable register_map until the argument is renamed in the HLS source. If you prefer the check, I can change the PR to that.

Tests added to tests/test_registers.py:

  • A register map with one register per name (address, width, debug, access), each read-write and read-only. It reads the field, writes it through the register and through the map, checks repr and writes CTRL.
  • A Register subclass with such a field and debug=True still prints the register address.
  • A plain Register still reads and sets address, width, debug and access. This one passes before and after.

How I found it

I was going through open issues in Xilinx repos and picked #1480 because it had a full traceback. I reproduced it with a RegisterMap built from an ip_dict style description with an HLS CTRL register plus one argument register. Then I tried the other attribute names set in Register.__init__, and also buffer and count, to see which names collide.

Where this can show up in practice

#1480 is a field report for width from an HLS IP with width and height arguments, where the driver worked only after renaming them to cols and rows. address, access and debug fail the same way in the code path, but I only know that from the reproduction, not from a user report.

Verification (macOS, arm64, Python 3.11)

  • pytest --doctest-modules as in CI:
    • Before: 310 passed, 2 skipped.
    • After: 324 passed, 2 skipped. pynq/registers.py coverage stays at 100 %.
  • The 12 new name-collision tests fail on pynq-next with the errors in the table and pass with the change.
  • The reproduction script: all names in the table work after the change, for read-write and read-only fields.
  • Both flake8 commands from CI. The strict one finds 0 errors. The warnings in pynq/registers.py are the same three as before (E741, E501, W391), all on lines this PR doesn't touch.

Not run:

  • No board or pynq.remote. I only used buffers and the mock devices from the tests.
  • Linux and the other Python versions in the CI matrix (3.10, 3.12).

Refs #1480

Register kept its own address, width, debug flag and access mode in
public attributes. A subclass made by create_subclass adds a property
per field, so a field with one of those names (HLS IP gets one field
per scalar argument, e.g. width) took over the attribute: building the
RegisterMap failed with RecursionError, AttributeError or TypeError.

Store the state under private names and use those internally. The
public names stay available as properties on Register, so plain
registers behave as before; on a register with such a field the name
now refers to the field.

Refs Xilinx#1480

Signed-off-by: Dezhen Lu <dezhen.lu@student.uni-tuebingen.de>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant