swig, generator: unify accessor annotations and add custom-access groundwork#3315
Open
martin-belanger wants to merge 2 commits intolinux-nvme:masterfrom
Open
Conversation
Rename the member-level annotation prefix from !accessors: to !access:
to decouple it from the !generate-accessors struct-level annotation.
Until now, the !accessors:<value> member annotation was consumed only
by the accessor generator, and its name reflected that — it read as a
natural companion to the struct-level !generate-accessors annotation.
That one-to-one relationship is about to change. An upcoming
!generate-python struct-level annotation will also need to read the
same member annotations, both to drive the generated SWIG layer and to
validate consistency between the C and Python sides. The annotation is
no longer the private concern of the accessor generator.
Keeping the name !accessors: would make that relationship confusing:
- The visual similarity to !generate-accessors suggests the member
annotation is owned by accessor generation, when in fact multiple
generators will consume it.
- Readers (and future contributors adding more generators) would
reasonably — but wrongly — assume the annotation is accessor
specific and only relevant when !generate-accessors is set.
Renaming to !access: breaks that false association. The new name also
reads more naturally as English:
char *name; // !access:readonly
char *addr; // !access:none
vs.
char *name; // !accessors:readonly
char *addr; // !accessors:none
This patch is a pure rename with no behavioural change:
- generate-accessors.py: update has_annotation() lookups and the
docstring examples
- private.h: rename all 47 member annotations
- generate-accessors.md: update every example, table row and note;
re-pad the affected table rows to preserve column alignment
Generator output (accessors.h / accessors.c / accessors.ld) is byte
identical before and after this commit.
Signed-off-by: Martin Belanger <Martin.Belanger@dell.com>
Assisted-by: Claude Opus 4.7 <noreply@anthropic.com>
igaw
reviewed
Apr 24, 2026
igaw
reviewed
Apr 24, 2026
Author
|
If it helps, we could also consider making I can make that change if you'd like. |
Replace the single-mode !access:<value> annotation with an orthogonal
two-axis spec:
!access:read=<mode>,write=<mode>
where read and write are independent and each takes one of:
generated (generator emits the accessor), custom (hand-written
accessor in the public API, generator emits nothing), or none (no
accessor exists). The same spec is accepted at the struct level via
!generate-accessors:read=<mode>,write=<mode>, with per-axis
inheritance from the struct-level default to member-level overrides.
The new model lets downstream consumers (the Python-binding generator,
the nvme.i consistency check) distinguish "no accessor" from
"hand-written accessor", and cleanly expresses mixed cases such as
"generated getter + hand-written setter" that the old one-dimensional
annotation could not name. This is a clean break: the old :none /
:readonly / :writeonly / :readwrite tokens are no longer recognised.
See libnvme/tools/generator/generate-accessors.md for the full syntax,
inheritance rules, and examples.
All 47 !access: annotations in private.h are updated accordingly. The
regenerated accessors.{h,c,ld} are byte-identical to the pre-change
baseline.
Signed-off-by: Martin Belanger <Martin.Belanger@dell.com>
Assisted-by: Claude Opus 4.7 <noreply@anthropic.com>
martin-belanger
force-pushed
the
libnvme-python-bindings-redesign-plan-1
branch
from
290e916 to
1a0ccef
Compare
Author
|
By setting the struct-level defaults I was able to reduce the number of member-level overrides. BTW, we may need to revisit the member annotations. I'm not sure that we need accessors for all of them For example, we are generating accessors for |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR contains two small, incremental patches that prepare the codebase for upcoming work on Python/SWIG binding generation.
The goal is to make accessor semantics explicit and machine-readable so downstream tooling can reason about read/write behavior and custom implementations.
Patch 1: Rename annotation
!accessors:*→!access:*Patch 2: Explicit access model + custom support
Introduce a unified annotation model:
!access:read=<mode>,write=<mode>!generate-accessors:read=<mode>,write=<mode>Modes:
generated,custom,noneStruct-level annotations define defaults; member-level overrides per axis
Add support in the generator
Update documentation
Annotate existing fields that already rely on custom accessors
Rationale
The previous annotation scheme could not clearly express:
This becomes important for:
These changes establish a clear and extensible model without altering existing runtime behavior.
Notes
Feedback welcome before building on top of this.