generate-accessors: annotation style + lifecycle generation

libnvme/examples/discover-loop.c

@@ -94,7 +94,7 @@ int main()
 		goto free_fctx;
 	}
 
-	ret = libnvmf_discovery_args_create(&args);
+	ret = libnvmf_discovery_args_new(&args);
 	if (!ret) {
 		libnvmf_discovery_args_set_max_retries(args, 4);
 		ret = libnvmf_get_discovery_log(c, args, &log);

libnvme/libnvme/nvme.i

@@ -829,7 +829,7 @@ struct libnvmf_context {};
 			discover_err = 1;
 			return NULL;
 		}
-		discover_err = libnvmf_discovery_args_create(&args);
+		discover_err = libnvmf_discovery_args_new(&args);
 		if (discover_err)
 			return NULL;
 		libnvmf_discovery_args_set_lsp(args, lsp);

libnvme/src/accessors-fabrics.ld

@@ -10,8 +10,11 @@
 
 LIBNVMF_ACCESSORS_3 {
 	global:
+		libnvmf_discovery_args_free;
 		libnvmf_discovery_args_get_lsp;
 		libnvmf_discovery_args_get_max_retries;
+		libnvmf_discovery_args_init_defaults;
+		libnvmf_discovery_args_new;
 		libnvmf_discovery_args_set_lsp;
 		libnvmf_discovery_args_set_max_retries;
 		libnvmf_uri_get_fragment;

libnvme/src/libnvmf.ld

@@ -24,8 +24,6 @@ LIBNVMF_3 {
 		libnvmf_ctrl_get_fabrics_config;
 		libnvmf_disconnect_ctrl;
 		libnvmf_discovery;
-		libnvmf_discovery_args_create;
-		libnvmf_discovery_args_free;
 		libnvmf_discovery_config_file;
 		libnvmf_discovery_config_json;
 		libnvmf_discovery_nbft;

libnvme/src/nvme/accessors-fabrics.c

@@ -17,6 +17,7 @@
  * To update run: meson compile -C [BUILD-DIR] update-accessors
  * Or:            make update-accessors
  */
+#include <errno.h>
 #include <stdlib.h>
 #include <string.h>
 #include "accessors-fabrics.h"
@@ -28,6 +29,31 @@
  * Accessors for: struct libnvmf_discovery_args
  ****************************************************************************/
 
+__public int libnvmf_discovery_args_new(struct libnvmf_discovery_args **pp)
+{
+	if (!pp)
+		return -EINVAL;
+	*pp = calloc(1, sizeof(struct libnvmf_discovery_args));
+	if (!*pp)
+		return -ENOMEM;
+	libnvmf_discovery_args_init_defaults(*pp);
+	return 0;
+}
+
+__public void libnvmf_discovery_args_free(struct libnvmf_discovery_args *p)
+{
+	free(p);
+}
+
+__public void libnvmf_discovery_args_init_defaults(
+		struct libnvmf_discovery_args *p)
+{
+	if (!p)
+		return;
+	p->max_retries = 6;
+	p->lsp = NVMF_LOG_DISC_LSP_NONE;
+}
+
 __public void libnvmf_discovery_args_set_max_retries(
 		struct libnvmf_discovery_args *p,
 		int max_retries)

libnvme/src/nvme/accessors-fabrics.h

@@ -35,6 +35,36 @@ struct libnvmf_uri;
  * Accessors for: struct libnvmf_discovery_args
  ****************************************************************************/
 
+/**
+ * libnvmf_discovery_args_new() - Allocate and initialise a new instance.
+ * @pp: On success, *pp is set to the newly allocated object.
+ *
+ * Allocates a zeroed &struct libnvmf_discovery_args on the heap.
+ * The caller must release it with libnvmf_discovery_args_free().
+ *
+ * Return: 0 on success, -EINVAL if @pp is NULL,
+ *         -ENOMEM if allocation fails.
+ */
+int libnvmf_discovery_args_new(struct libnvmf_discovery_args **pp);
+
+/**
+ * libnvmf_discovery_args_free() - Release a libnvmf_discovery_args object.
+ * @p: Object previously returned by libnvmf_discovery_args_new().
+ *     A NULL pointer is silently ignored.
+ */
+void libnvmf_discovery_args_free(struct libnvmf_discovery_args *p);
+
+/**
+ * libnvmf_discovery_args_init_defaults() - Set fields to their defaults.
+ * @p: The &struct libnvmf_discovery_args instance to initialise.
+ *
+ * Sets each field that carries a default annotation to its
+ * compile-time default value.  Called automatically by
+ * libnvmf_discovery_args_new() but may also be called directly to reset an
+ * instance to its defaults without reallocating it.
+ */
+void libnvmf_discovery_args_init_defaults(struct libnvmf_discovery_args *p);
+
 /**
  * libnvmf_discovery_args_set_max_retries() - Set max_retries.
  * @p: The &struct libnvmf_discovery_args instance to update.

libnvme/src/nvme/accessors.c

@@ -17,6 +17,7 @@
  * To update run: meson compile -C [BUILD-DIR] update-accessors
  * Or:            make update-accessors
  */
+#include <errno.h>
 #include <stdlib.h>
 #include <string.h>
 #include "accessors.h"

libnvme/src/nvme/accessors.h

@@ -236,7 +236,7 @@ long libnvme_fabrics_config_get_tls_key_id(
 		const struct libnvme_fabrics_config *p);
 
 /**
- * libnvme_fabrics_config_set_tls_configured_key_id() - Set tls_configured_key_id.
+ * libnvme_fabrics_config_set_tls_configured_key_id() - Setter.
  * @p: The &struct libnvme_fabrics_config instance to update.
  * @tls_configured_key_id: Value to assign to the tls_configured_key_id field.
  */
@@ -245,7 +245,7 @@ void libnvme_fabrics_config_set_tls_configured_key_id(
 		long tls_configured_key_id);
 
 /**
- * libnvme_fabrics_config_get_tls_configured_key_id() - Get tls_configured_key_id.
+ * libnvme_fabrics_config_get_tls_configured_key_id() - Getter.
  * @p: The &struct libnvme_fabrics_config instance to query.
  *
  * Return: The value of the tls_configured_key_id field.

libnvme/src/nvme/fabrics.c

@@ -1496,32 +1496,6 @@ static void sanitize_discovery_log_entry(struct libnvme_global_ctx *ctx,
 	}
 }
 
-__public int libnvmf_discovery_args_create(struct libnvmf_discovery_args **argsp)
-{
-	struct libnvmf_discovery_args *args;
-
-	if (!argsp)
-		return -EINVAL;
-
-	args = calloc(1, sizeof(*args));
-	if (!args)
-		return -ENOMEM;
-
-	args->max_retries = 6;
-	args->lsp = NVMF_LOG_DISC_LSP_NONE;
-
-	*argsp = args;
-	return 0;
-}
-
-__public void libnvmf_discovery_args_free(struct libnvmf_discovery_args *args)
-{
-	if (!args)
-		return;
-
-	free(args);
-}
-
 __public int libnvmf_get_discovery_log(libnvme_ctrl_t ctrl,
 				    const struct libnvmf_discovery_args *args,
 				    struct nvmf_discovery_log **logp)

libnvme/src/nvme/fabrics.h

@@ -157,7 +157,7 @@ int libnvmf_connect_ctrl(libnvme_ctrl_t c);
 /*
  * struct libnvmf_discovery_args - Opaque arguments for libnvmf_get_discovery_log()
  *
- * Allocate with libnvmf_discovery_args_create() and release with
+ * Allocate with libnvmf_discovery_args_new() and release with
  * libnvmf_discovery_args_free(). Use the setter/getter accessors to configure
  * fields; do not access members directly.
  */
@@ -168,23 +168,6 @@ struct libnvmf_discovery_args;
  */
 struct libnvmf_uri;
 
-/**
- * libnvmf_discovery_args_create() - Allocate a discovery args object
- * @argsp:	On success, set to the newly allocated object
- *
- * Allocates and initialises a &struct libnvmf_discovery_args with sensible
- * defaults. The caller must release it with libnvmf_discovery_args_free().
- *
- * Return: 0 on success, or a negative error code on failure.
- */
-int libnvmf_discovery_args_create(struct libnvmf_discovery_args **argsp);
-
-/**
- * libnvmf_discovery_args_free() - Release a discovery args object
- * @args:	Object previously returned by libnvmf_discovery_args_create()
- */
-void libnvmf_discovery_args_free(struct libnvmf_discovery_args *args);
-
 /**
  * libnvmf_get_discovery_log() - Fetch the NVMe-oF discovery log page
  * @ctrl:	Discovery controller

libnvme/src/nvme/private-fabrics.h

@@ -78,9 +78,9 @@ struct libnvmf_context {
  * rest of the fabrics layer.
  */
 
-struct libnvmf_discovery_args { /*!generate-accessors*/
-	int max_retries;
-	__u8 lsp;
+struct libnvmf_discovery_args { // !generate-accessors !generate-lifecycle
+	int max_retries; // !default:6
+	__u8 lsp;        // !default:NVMF_LOG_DISC_LSP_NONE
 };
 
 /**
@@ -95,7 +95,7 @@ struct libnvmf_discovery_args { /*!generate-accessors*/
  * @fragment:		Optional fragment identifier component
  *			(separated by '#')
  */
-struct libnvmf_uri { //!generate-accessors
+struct libnvmf_uri { // !generate-accessors
 	char *scheme;
 	char *protocol;
 	char *userinfo;

libnvme/src/nvme/private.h

@@ -102,7 +102,7 @@ struct linux_passthru_cmd64 {
  * @tls:		Start TLS on the connection (TCP)
  * @concat:		Enable secure concatenation (TCP)
  */
-struct libnvme_fabrics_config { //!generate-accessors
+struct libnvme_fabrics_config { // !generate-accessors
 	int queue_size;
 	int nr_io_queues;
 	int reconnect_delay;
@@ -167,7 +167,7 @@ struct libnvme_transport_handle {
 	struct libnvme_log *log;
 };
 
-struct libnvme_path { /*!generate-accessors*/
+struct libnvme_path { // !generate-accessors
 	struct list_node entry;
 	struct list_node nentry;
 
@@ -179,7 +179,7 @@ struct libnvme_path { /*!generate-accessors*/
 	char *ana_state;
 	char *numa_nodes;
 	int grpid;
-	int queue_depth; //!accessors:none
+	int queue_depth; // !accessors:none
 };
 
 struct libnvme_ns_head {
@@ -189,7 +189,7 @@ struct libnvme_ns_head {
 	char *sysfs_dir;
 };
 
-struct libnvme_ns { /*!generate-accessors*/
+struct libnvme_ns { // !generate-accessors
 	struct list_node entry;
 
 	struct libnvme_subsystem *s;
@@ -200,7 +200,7 @@ struct libnvme_ns { /*!generate-accessors*/
 	struct libnvme_transport_handle *hdl;
 	__u32 nsid;
 	char *name;
-	char *generic_name; //!accessors:none
+	char *generic_name; // !accessors:none
 	char *sysfs_dir;
 
 	int lba_shift;
@@ -215,78 +215,78 @@ struct libnvme_ns { /*!generate-accessors*/
 	enum nvme_csi csi;
 };
 
-struct libnvme_ctrl { /*!generate-accessors*/
+struct libnvme_ctrl { // !generate-accessors
 	struct list_node entry;
 	struct list_head paths;
 	struct list_head namespaces;
 	struct libnvme_subsystem *s;
 
 	struct libnvme_global_ctx *ctx;
 	struct libnvme_transport_handle *hdl;
-	char *name; //!accessors:readonly
-	char *sysfs_dir; //!accessors:readonly
-	char *address; //!accessors:none
-	char *firmware; //!accessors:readonly
-	char *model; //!accessors:readonly
-	char *state; //!accessors:none
-	char *numa_node; //!accessors:readonly
-	char *queue_count; //!accessors:readonly
-	char *serial; //!accessors:readonly
-	char *sqsize; //!accessors:readonly
-	char *transport; //!accessors:readonly
-	char *subsysnqn; //!accessors:readonly
-	char *traddr; //!accessors:readonly
-	char *trsvcid; //!accessors:readonly
+	char *name; // !accessors:readonly
+	char *sysfs_dir; // !accessors:readonly
+	char *address; // !accessors:none
+	char *firmware; // !accessors:readonly
+	char *model; // !accessors:readonly
+	char *state; // !accessors:none
+	char *numa_node; // !accessors:readonly
+	char *queue_count; // !accessors:readonly
+	char *serial; // !accessors:readonly
+	char *sqsize; // !accessors:readonly
+	char *transport; // !accessors:readonly
+	char *subsysnqn; // !accessors:readonly
+	char *traddr; // !accessors:readonly
+	char *trsvcid; // !accessors:readonly
 	char *dhchap_host_key;
 	char *dhchap_ctrl_key;
 	char *keyring;
 	char *tls_key_identity;
 	char *tls_key;
-	char *cntrltype; //!accessors:readonly
-	char *cntlid; //!accessors:readonly
-	char *dctype; //!accessors:readonly
-	char *phy_slot; //!accessors:readonly
-	char *host_traddr; //!accessors:readonly
-	char *host_iface; //!accessors:readonly
+	char *cntrltype; // !accessors:readonly
+	char *cntlid; // !accessors:readonly
+	char *dctype; // !accessors:readonly
+	char *phy_slot; // !accessors:readonly
+	char *host_traddr; // !accessors:readonly
+	char *host_iface; // !accessors:readonly
 	bool discovery_ctrl;
 	bool unique_discovery_ctrl;
 	bool discovered;
 	bool persistent;
 	struct libnvme_fabrics_config cfg;
 };
 
-struct libnvme_subsystem { /*!generate-accessors*/
+struct libnvme_subsystem { // !generate-accessors
 	struct list_node entry;
 	struct list_head ctrls;
 	struct list_head namespaces;
 	struct libnvme_host *h;
 
-	char *name; /*!accessors:readonly*/
-	char *sysfs_dir; /*!accessors:readonly*/
-	char *subsysnqn; /*!accessors:readonly*/
-	char *model; /*!accessors:readonly*/
-	char *serial; /*!accessors:readonly*/
-	char *firmware; /*!accessors:readonly*/
-	char *subsystype; /*!accessors:readonly*/
+	char *name; // !accessors:readonly
+	char *sysfs_dir; // !accessors:readonly
+	char *subsysnqn; // !accessors:readonly
+	char *model; // !accessors:readonly
+	char *serial; // !accessors:readonly
+	char *firmware; // !accessors:readonly
+	char *subsystype; // !accessors:readonly
 	char *application;
 	char *iopolicy;
 };
 
-struct libnvme_host { /*!generate-accessors*/
+struct libnvme_host { // !generate-accessors
 	struct list_node entry;
 	struct list_head subsystems;
 	struct libnvme_global_ctx *ctx;
 
-	char *hostnqn; /*!accessors:readonly*/
-	char *hostid; /*!accessors:readonly*/
+	char *hostnqn; // !accessors:readonly
+	char *hostid; // !accessors:readonly
 	char *dhchap_host_key;
 	char *hostsymname;
-	bool pdc_enabled; //!accessors:none
+	bool pdc_enabled; // !accessors:none
 	bool pdc_enabled_valid; /* set if pdc_enabled doesn't have an undefined
 				 * value */
 };
 
-struct libnvme_fabric_options { /*!generate-accessors*/
+struct libnvme_fabric_options { // !generate-accessors
 	bool cntlid;
 	bool concat;
 	bool ctrl_loss_tmo;

libnvme/test/ioctl/discovery.c

@@ -45,7 +45,7 @@ static int fetch_discovery_log(libnvme_ctrl_t c,
 	struct libnvmf_discovery_args *args;
 	int err;
 
-	err = libnvmf_discovery_args_create(&args);
+	err = libnvmf_discovery_args_new(&args);
 	if (err)
 		return err;
 	libnvmf_discovery_args_set_max_retries(args, max_retries);