Skip to content

generate-accessors: annotation style + lifecycle generation#3288

Merged
igaw merged 2 commits intolinux-nvme:masterfrom
martin-belanger:generate-lifecycle-v2
Apr 20, 2026
Merged

generate-accessors: annotation style + lifecycle generation#3288
igaw merged 2 commits intolinux-nvme:masterfrom
martin-belanger:generate-lifecycle-v2

Conversation

@martin-belanger
Copy link
Copy Markdown

This PR is a two-patch rework of the accessor generator, split from the earlier generate-lifecycle branch per reviewer's request for smaller incremental patches (see earlier PR: #3283).

Patch 1 — Switch annotations to // comment style

Replaces the /*!annotation*/ block-comment style with // !annotation line comments. The canonical form is // !token (one space between // and !). The parser accepts any amount of whitespace between // and !, so //!token, // !token, and //\t!token are all equivalent — making annotations resilient to contributor variation.

Updates all annotated structs in private.h and private-fabrics.h, and updates the documentation and helper scripts. The generated accessors.{h,c} and accessors-fabrics.{h,c} are unchanged by this patch.

Patch 2 — Add lifecycle and default-value generation

Extends the generator with two new annotations:

  • // !generate-lifecycle (on a struct brace) — generates _new(), _free(), and (when defaults exist) _init_defaults()
  • // !default:<value> (on a member line) — sets the initial value of that member in _init_defaults()

Applies // !generate-lifecycle to struct libnvmf_discovery_args, replacing the hand-written libnvmf_discovery_args_create() / _free() pair:

  • libnvmf_discovery_args_new() replaces libnvmf_discovery_args_create() — same int return / double-pointer signature; sets defaults via libnvmf_discovery_args_init_defaults()
  • libnvmf_discovery_args_free() is now generated (same name, same semantics — NULL-safe via free(NULL))
  • libnvmf_discovery_args_init_defaults() is new; sets max_retries = 6 and lsp = NVMF_LOG_DISC_LSP_NONE

Updates all callers (nvme.i, discover-loop.c, test/ioctl/discovery.c) to use the new _new() API. Moves the ABI entries for the removed functions from libnvmf.ld to accessors-fabrics.ld.

Note on _create_new renaming

A patch 3 to rename remaining _create functions to _new was considered but dropped. The _new suffix generated here carries a specific contract: allocate a zeroed struct on the heap, set default field values, and return it via a double-pointer with no other parameters. The remaining _create functions in the public API (libnvme_create_global_ctx, libnvme_create_raw_secret, libnvmf_context_create, libnvmf_create_ctrl) are fundamentally different — they accept multiple parameters and perform substantial initialization logic beyond just setting defaults. Renaming them to _new would misrepresent what they do and break the semantic contract that _new is meant to convey.

Martin Belanger added 2 commits April 20, 2026 07:03
Replace the /*!annotation*/ block-comment style with // line comments
throughout. The canonical form is '// !token' (one space between // and
!). The parser accepts any amount of whitespace between // and !, so
'//!token', '// !token', and '//\t!token' are all equivalent. This
makes the annotation resilient to contributor variation.

Update all annotated structs in private.h and private-fabrics.h, and
update the documentation and helper scripts accordingly. The generated
accessors.{h,c} and accessors-fabrics.{h,c} are unchanged.

Signed-off-by: Martin Belanger <[email protected]>
Extend the generator with two new annotations:

  // !generate-lifecycle   (on struct brace) -- generate _new(), _free(),
                            and (when defaults exist) _init_defaults()
  // !default:<value>      (on a member line) -- set the initial value of
                            that member in _init_defaults()

Apply // !generate-lifecycle to struct libnvmf_discovery_args, replacing
the hand-written libnvmf_discovery_args_create() / _free() pair:

  - libnvmf_discovery_args_new() replaces libnvmf_discovery_args_create().
    Same int return / double-pointer signature; sets defaults via
    libnvmf_discovery_args_init_defaults().
  - libnvmf_discovery_args_free() is now generated (same name, same
    semantics -- NULL-safe via free(NULL)).
  - libnvmf_discovery_args_init_defaults() is new; sets max_retries = 6
    and lsp = NVMF_LOG_DISC_LSP_NONE.

Update all callers (nvme.i, discover-loop.c, test/ioctl/discovery.c) to
use the new _new() API. Move the ABI entries for the removed functions
from libnvmf.ld to accessors-fabrics.ld.

Signed-off-by: Martin Belanger <[email protected]>
@igaw igaw merged commit f018b37 into linux-nvme:master Apr 20, 2026
29 checks passed
@igaw
Copy link
Copy Markdown
Collaborator

igaw commented Apr 20, 2026

Thanks!

@martin-belanger martin-belanger deleted the generate-lifecycle-v2 branch April 20, 2026 22:23
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.

2 participants