From a7bafb612152486f5c78675ff8037ea9ae673def Mon Sep 17 00:00:00 2001 From: Jim Harris Date: Tue, 4 Sep 2018 10:06:11 -0700 Subject: [PATCH] bdev: clarify the config_json methods Signed-off-by: Jim Harris Change-Id: Ie2b0e24000665fd95a7c21298c86f4889a03650a Reviewed-on: https://review.gerrithub.io/424583 Tested-by: SPDK CI Jenkins Reviewed-by: Ben Walker Reviewed-by: Changpeng Liu Chandler-Test-Pool: SPDK Automated Test System --- include/spdk/bdev_module.h | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/include/spdk/bdev_module.h b/include/spdk/bdev_module.h index a7106a467..39e571b53 100644 --- a/include/spdk/bdev_module.h +++ b/include/spdk/bdev_module.h @@ -91,8 +91,16 @@ struct spdk_bdev_module { void (*config_text)(FILE *fp); /** - * Function called to return a text string representing the - * module's configuration options for inclusion in a configuration file. + * Function called to return a text string representing the module-level + * JSON RPCs required to regenerate the current configuration. This will + * include module-level configuration options, or methods to construct + * bdevs when one RPC may generate multiple bdevs (for example, an NVMe + * controller with multiple namespaces). + * + * Per-bdev JSON RPCs (where one "construct" RPC always creates one bdev) + * may be implemented here, or by the bdev's write_config_json function - + * but not both. Bdev module implementers may choose which mechanism to + * use based on the module's design. * * \return 0 on success or Bdev specific negative error code. */ @@ -185,7 +193,14 @@ struct spdk_bdev_fn_table { int (*dump_info_json)(void *ctx, struct spdk_json_write_ctx *w); /** - * Output bdev-specific configuration to a JSON stream. Optional - may be NULL. + * Output bdev-specific RPC configuration to a JSON stream. Optional - may be NULL. + * + * This function should only be implemented for bdevs which can be configured + * independently of other bdevs. For example, RPCs to create a bdev for an NVMe + * namespace may not be generated by this function, since enumerating an NVMe + * namespace requires attaching to an NVMe controller, and that controller may + * contain multiple namespaces. The spdk_bdev_module's config_json function should + * be used instead for these cases. * * The JSON write context will be initialized with an open object, so the bdev * driver should write all data necessary to recreate this bdev by invoking