libnvme, python: prep accessor generator for Python bindings redesign

[martin-belanger]

Summary

This patch prepares the accessor annotation system and code generator for the upcoming Python bindings redesign. No user-visible API changes are made; the changes either reduce annotation noise in private.h or extend the generator to handle types it previously silently skipped.

1. Annotation cleanup in private.h

The !generate-accessors struct-level default was optimised for three structs to minimise the number of per-member !access: overrides needed:

Struct	Old default	New default	Override reduction
libnvme_path	read=custom,write=none	(unchanged)	—
libnvme_ctrl	read=generated,write=none	(unchanged)	23 → 14
libnvme_subsystem	read=generated,write=none	(unchanged)	8 → 2

Note: nested embedded structs (e.g. struct list_node) and pointers-to-structs (e.g. struct libnvme_ctrl *c) are always (none,none) and are excluded from override counts — they are never annotated.

The stat-block members (stat[2], curr_idx, diffstat) that appear in both libnvme_path and libnvme_ns now carry a short block comment explaining their double-buffered design and that they are managed exclusively by the stat subsystem and must not be accessed directly. Both curr_idx and diffstat are now marked !access:read=none (no public getter) since they are implementation details.

The pdc_enabled / pdc_enabled_valid pair in libnvme_host also received a clarifying block comment explaining their relationship.

2. Generator extensions (generate-accessors.py)

Multi-word type support (MEMBER_RE):

The regex previously matched only single-word type names (uint8_t, bool, int). It now handles multi-word types such as enum nvme_csi, unsigned int, and unsigned long long. Backtracking in the regex engine resolves the inherent ambiguity between the last type-word and the member name; no downstream code in the generator required changes because the capture-group numbering is preserved.

Fixed-size scalar array support (SCALAR_ARRAY_RE):

A new regex and parse branch handle members of the form type name[N] (e.g. uint8_t eui64[8], unsigned char uuid[NVME_UUID_LEN]). char name[N] members are caught first by the existing CHAR_ARRAY_RE and never reach this path.

For such members the generator now emits:

• Getter — const type *nvme_X_get_Y(const struct X *p) returning p->y (pointer to first element). The KernelDoc explicitly states the size: "Return: Pointer to the y array of N type elements."
• Setter — void nvme_X_set_Y(struct X *p, const type y[N]) implemented with memcpy(p->y, y, sizeof(p->y)).

A const-qualified array member forces write=none regardless of the struct-level default, consistent with how const is handled for scalar members.

3. API rename: libnvme_ns_get_uuid → libnvme_ns_copy_uuid

The existing libnvme_ns_get_uuid(n, out) fills a caller-supplied buffer rather than returning a value, making "get" a misleading name. It is renamed to libnvme_ns_copy_uuid to make the copy semantics explicit.

Affected files: tree.h, tree.c, libnvme.ld, test/test.c.

The uuid member annotation in private.h is updated to !access:read=none,write=none — the two-argument copy signature is structurally incompatible with the single-argument getter pattern required by the Python %extend pseudo-member mechanism, so no Python property is generated for uuid. A dedicated Python helper can be added later if needed.

[igaw]

Thanks!