include/nvmf.h: add comments for public APIs

Change-Id: Ie921c78f09842f9c8d008cc18a4c7145b458b559
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/401782
Reviewed-by: GangCao <gang.cao@intel.com>
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Changpeng Liu <changpeng.liu@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>

include/spdk/nvmf.h

@@ -66,19 +66,24 @@ struct spdk_nvmf_tgt_opts {
 	uint32_t in_capsule_data_size;
 	uint32_t max_io_size;
 };
-
+/**
+ * Initialize the default value of opts.
+ *
+ * \param opts Data structure where SPDK will initialize the default options.
+ */
 void spdk_nvmf_tgt_opts_init(struct spdk_nvmf_tgt_opts *opts);
 
 /**
- * Construct an NVMe-oF target
+ * Construct an NVMe-oF target.
  *
- * \param opts Options
+ * \param opts Options.
- * \return An spdk_nvmf_tgt on success, NULL on failure.
+ *
+ * \return a pointer to a NVMe-oF target on success, or NULL on failure.
  */
 struct spdk_nvmf_tgt *spdk_nvmf_tgt_create(struct spdk_nvmf_tgt_opts *opts);
 
 /**
- * Destroy an NVMe-oF target
+ * Destroy an NVMe-oF target.
  *
  * \param tgt The target to destroy. This releases all resources.
  */
@@ -91,10 +96,10 @@ void spdk_nvmf_tgt_destroy(struct spdk_nvmf_tgt *tgt);
  * the connection based on a subsystem-specific whitelist. See
  * spdk_nvmf_subsystem_add_host() and spdk_nvmf_subsystem_add_listener()
  *
- * \param tgt The target associated with this listen address
+ * \param tgt The target associated with this listen address.
- * \param trid The address to listen at
+ * \param trid The address to listen at.
  *
- * \return 0 on success. Negated errno on failure.
+ * \return 0 on success, or negated errno on failure.
  */
 int spdk_nvmf_tgt_listen(struct spdk_nvmf_tgt *tgt,
 			 struct spdk_nvme_transport_id *trid);
@@ -107,27 +112,46 @@ typedef void (*new_qpair_fn)(struct spdk_nvmf_qpair *qpair);
  * The new_qpair_fn cb_fn will be called for each newly discovered
  * qpair. The user is expected to add that qpair to a poll group
  * to establish the connection.
+ *
+ * \param tgt The target associated with the listen address.
+ * \param cb_fn Called for each newly discovered qpair.
  */
 void spdk_nvmf_tgt_accept(struct spdk_nvmf_tgt *tgt, new_qpair_fn cb_fn);
 
 /**
  * Create a poll group.
+ *
+ * \param tgt The target to create a poll group.
+ *
+ * \return a poll group on success, or NULL on failure.
  */
 struct spdk_nvmf_poll_group *spdk_nvmf_poll_group_create(struct spdk_nvmf_tgt *tgt);
 
 /**
  * Destroy a poll group.
+ *
+ * \param group The poll group to destroy.
  */
 void spdk_nvmf_poll_group_destroy(struct spdk_nvmf_poll_group *group);
 
 /**
  * Add the given qpair to the poll group.
+ *
+ * \param group The group to add qpair to.
+ * \param qpair The qpair to add.
+ *
+ * \return 0 on success, -1 on failure.
  */
 int spdk_nvmf_poll_group_add(struct spdk_nvmf_poll_group *group,
 			     struct spdk_nvmf_qpair *qpair);
 
 /**
  * Remove the given qpair from the poll group.
+ *
+ * \param group The group to delete qpair from.
+ * \param qpair The qpair to remove.
+ *
+ * \return 0 on success, -1 on failure.
  */
 int spdk_nvmf_poll_group_remove(struct spdk_nvmf_poll_group *group,
 				struct spdk_nvmf_qpair *qpair);
@@ -146,7 +170,7 @@ int spdk_nvmf_poll_group_remove(struct spdk_nvmf_poll_group *group,
  * \param type Whether this subsystem is an I/O subsystem or a Discovery subsystem.
  * \param num_ns The number of namespaces this subsystem contains.
  *
- * \return An spdk_nvmf_subsystem or NULL on error.
+ * \return a pointer to a NVMe-oF subsystem on success, or NULL on failure.
  */
 struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_create(struct spdk_nvmf_tgt *tgt,
 		const char *nqn,
@@ -171,8 +195,8 @@ typedef void (*spdk_nvmf_subsystem_state_change_done)(struct spdk_nvmf_subsystem
  * \param cb_fn A function that will be called once the subsystem has changed state.
  * \param cb_arg Argument passed to cb_fn.
  *
- * \return 0 on success. Negated errno on failure. The callback provided
+ * \return 0 on success, or negated errno on failure. The callback provided will only
- *	     will only be called on success.
+ * be called on success.
  */
 int spdk_nvmf_subsystem_start(struct spdk_nvmf_subsystem *subsystem,
 			      spdk_nvmf_subsystem_state_change_done cb_fn,
@@ -185,8 +209,8 @@ int spdk_nvmf_subsystem_start(struct spdk_nvmf_subsystem *subsystem,
  * \param cb_fn A function that will be called once the subsystem has changed state.
  * \param cb_arg Argument passed to cb_fn.
  *
- * \return 0 on success. Negated errno on failure. The callback provided
+ * \return 0 on success, or negated errno on failure. The callback provided will only
- *	     will only be called on success.
+ * be called on success.
  */
 int spdk_nvmf_subsystem_stop(struct spdk_nvmf_subsystem *subsystem,
 			     spdk_nvmf_subsystem_state_change_done cb_fn,
@@ -199,8 +223,8 @@ int spdk_nvmf_subsystem_stop(struct spdk_nvmf_subsystem *subsystem,
  * \param cb_fn A function that will be called once the subsystem has changed state.
  * \param cb_arg Argument passed to cb_fn.
  *
- * \return 0 on success. Negated errno on failure. The callback provided
+ * \return 0 on success, or negated errno on failure. The callback provided will only
- *	     will only be called on success.
+ * be called on success.
  */
 int spdk_nvmf_subsystem_pause(struct spdk_nvmf_subsystem *subsystem,
 			      spdk_nvmf_subsystem_state_change_done cb_fn,
@@ -213,26 +237,39 @@ int spdk_nvmf_subsystem_pause(struct spdk_nvmf_subsystem *subsystem,
  * \param cb_fn A function that will be called once the subsystem has changed state.
  * \param cb_arg Argument passed to cb_fn.
  *
- * \return 0 on success. Negated errno on failure. The callback provided
+ * \return 0 on success, or negated errno on failure. The callback provided will only
- *	     will only be called on success.
+ * be called on success.
  */
 int spdk_nvmf_subsystem_resume(struct spdk_nvmf_subsystem *subsystem,
 			       spdk_nvmf_subsystem_state_change_done cb_fn,
 			       void *cb_arg);
 
 /**
- * Search the target for a subsystem with the given NQN
+ * Search the target for a subsystem with the given NQN.
+ *
+ * \param tgt The NVMe-oF target to search from.
+ * \param subnqn NQN of the subsystem.
+ *
+ * \return a pointer to the NVMe-oF subsystem on success, or NULL on failure.
  */
 struct spdk_nvmf_subsystem *spdk_nvmf_tgt_find_subsystem(struct spdk_nvmf_tgt *tgt,
 		const char *subnqn);
 
 /**
  * Begin iterating over all known subsystems. If no subsystems are present, return NULL.
+ *
+ * \param tgt The NVMe-oF target to iterate.
+ *
+ * \return a pointer to the NVMe-oF subsystem on success, or NULL on failure.
  */
 struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_first(struct spdk_nvmf_tgt *tgt);
 
 /**
  * Continue iterating over all known subsystems. If no additional subsystems, return NULL.
+ *
+ * \param tgt The NVMe-oF target to iterate.
+ *
+ * \return a pointer to the NVMe-oF subsystem on success, or NULL on failure.
  */
 struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_next(struct spdk_nvmf_subsystem *subsystem);
 
@@ -241,9 +278,10 @@ struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_next(struct spdk_nvmf_subsys
  *
  * May only be performed on subsystems in the PAUSED or INACTIVE states.
  *
- * \param subsystem Subsystem to add host to
+ * \param subsystem Subsystem to add host to.
- * \param host_nqn The NQN for the host
+ * \param host_nqn The NQN for the host.
- * \return 0 on success. Negated errno value on failure.
+ *
+ * \return 0 on success, or negated errno value on failure.
  */
 int spdk_nvmf_subsystem_add_host(struct spdk_nvmf_subsystem *subsystem,
 				 const char *hostnqn);
@@ -253,9 +291,10 @@ int spdk_nvmf_subsystem_add_host(struct spdk_nvmf_subsystem *subsystem,
  *
  * May only be performed on subsystems in the PAUSED or INACTIVE states.
  *
- * \param subsystem Subsystem to remove host from
+ * \param subsystem Subsystem to remove host from.
- * \param host_nqn The NQN for the host
+ * \param host_nqn The NQN for the host.
- * \return 0 on success. Negated errno value on failure.
+ *
+ * \return 0 on success, or negated errno value on failure.
  */
 int spdk_nvmf_subsystem_remove_host(struct spdk_nvmf_subsystem *subsystem, const char *hostnqn);
 
@@ -265,9 +304,10 @@ int spdk_nvmf_subsystem_remove_host(struct spdk_nvmf_subsystem *subsystem, const
  * May only be performed on subsystems in the PAUSED or INACTIVE states.
  *
  * \param subsystem Subsystem to modify.
- * \param allow_any_host true to allow any host to connect to this subsystem, or false to enforce
+ * \param allow_any_host true to allow any host to connect to this subsystem,
- *                       the whitelist configured with spdk_nvmf_subsystem_add_host().
+ * or false to enforce the whitelist configured with spdk_nvmf_subsystem_add_host().
- * \return 0 on success. Negated errno value on failure.
+ *
+ * \return 0 on success, or negated errno value on failure.
  */
 int spdk_nvmf_subsystem_set_allow_any_host(struct spdk_nvmf_subsystem *subsystem,
 		bool allow_any_host);
@@ -276,54 +316,60 @@ int spdk_nvmf_subsystem_set_allow_any_host(struct spdk_nvmf_subsystem *subsystem
  * Check whether a subsystem should allow any host or only hosts in the allowed list.
  *
  * \param subsystem Subsystem to modify.
- * \return true if any host is allowed to connect to this subsystem, or false if connecting hosts
+ *
- *         must be in the whitelist configured with spdk_nvmf_subsystem_add_host().
+ * \return true if any host is allowed to connect to this subsystem, or false if
+ * connecting hosts must be in the whitelist configured with spdk_nvmf_subsystem_add_host().
  */
 bool spdk_nvmf_subsystem_get_allow_any_host(const struct spdk_nvmf_subsystem *subsystem);
 
 /**
  * Check if the given host is allowed to connect to the subsystem.
  *
- * \param subsystem The subsystem to query
+ * \param subsystem The subsystem to query.
- * \param hostnqn The NQN of the host
+ * \param hostnqn The NQN of the host.
+ *
  * \return true if allowed, false if not.
  */
 bool spdk_nvmf_subsystem_host_allowed(struct spdk_nvmf_subsystem *subsystem, const char *hostnqn);
 
 /**
- * Return the first allowed host in a subsystem.
+ * Get the first allowed host in a subsystem.
  *
  * \param subsystem Subsystem to query.
- * \return First allowed host in this subsystem, or NULL if none allowed.
+ *
+ * \return first allowed host in this subsystem, or NULL if none allowed.
  */
 struct spdk_nvmf_host *spdk_nvmf_subsystem_get_first_host(struct spdk_nvmf_subsystem *subsystem);
 
 /**
- * Return the next allowed host in a subsystem.
+ * Get the next allowed host in a subsystem.
  *
  * \param subsystem Subsystem to query.
  * \param prev_host Previous host returned from this function.
- * \return Next allowed host in this subsystem, or NULL if prev_host was the last host.
+ *
+ * \return next allowed host in this subsystem, or NULL if prev_host was the last host.
  */
 struct spdk_nvmf_host *spdk_nvmf_subsystem_get_next_host(struct spdk_nvmf_subsystem *subsystem,
 		struct spdk_nvmf_host *prev_host);
 
 /**
- * Get a host's NQN
+ * Get a host's NQN.
  *
  * \param host Host to query.
+ *
  * \return NQN of host.
  */
 const char *spdk_nvmf_host_get_nqn(struct spdk_nvmf_host *host);
 
 /**
- * Accept new connections on the address provided
+ * Accept new connections on the address provided.
  *
  * May only be performed on subsystems in the PAUSED or INACTIVE states.
  *
- * \param subsystem Subsystem to add listener to
+ * \param subsystem Subsystem to add listener to.
- * \param trid The address to accept connections from
+ * \param trid The address to accept connections from.
- * \return 0 on success. Negated errno value on failure.
+ *
+ * \return 0 on success, or negated errno value on failure.
  */
 int spdk_nvmf_subsystem_add_listener(struct spdk_nvmf_subsystem *subsystem,
 				     struct spdk_nvme_transport_id *trid);
@@ -333,38 +379,44 @@ int spdk_nvmf_subsystem_add_listener(struct spdk_nvmf_subsystem *subsystem,
  *
  * May only be performed on subsystems in the PAUSED or INACTIVE states.
  *
- * \param subsystem Subsystem to remove listener from
+ * \param subsystem Subsystem to remove listener from.
- * \param trid The address to no longer accept connections from
+ * \param trid The address to no longer accept connections from.
- * \return 0 on success. Negated errno value on failure.
+ *
+ * \return 0 on success, or negated errno value on failure.
  */
 int spdk_nvmf_subsystem_remove_listener(struct spdk_nvmf_subsystem *subsystem,
 					const struct spdk_nvme_transport_id *trid);
 
 /**
- * Check if connections originated from the given address are allowed to connect to the subsystem.
+ * Check if connections originated from the given address are allowed to connect
+ * to the subsystem.
  *
- * \param subsystem The subsystem to query
+ * \param subsystem The subsystem to query.
- * \param trid The listen address
+ * \param trid The listen address.
- * \return true if allowed, false if not.
+ *
+ * \return true if allowed, or false if not.
  */
 bool spdk_nvmf_subsystem_listener_allowed(struct spdk_nvmf_subsystem *subsystem,
 		struct spdk_nvme_transport_id *trid);
 
 /**
- * Return the first allowed listen address in the subsystem.
+ * Get the first allowed listen address in the subsystem.
  *
  * \param subsystem Subsystem to query.
- * \return First allowed listen address in this subsystem, or NULL if none allowed.
+ *
+ * \return first allowed listen address in this subsystem, or NULL if none allowed.
  */
 struct spdk_nvmf_listener *spdk_nvmf_subsystem_get_first_listener(
 	struct spdk_nvmf_subsystem *subsystem);
 
 /**
- * Return the next allowed listen address in a subsystem.
+ * Get the next allowed listen address in a subsystem.
  *
  * \param subsystem Subsystem to query.
- * \param prev_listener Previous listen address for this subsystem
+ * \param prev_listener Previous listen address for this subsystem.
- * \return Next allowed listen address in this subsystem, or NULL if prev_listener was the last address.
+ *
+ * \return next allowed listen address in this subsystem, or NULL if prev_listener
+ * was the last address.
  */
 struct spdk_nvmf_listener *spdk_nvmf_subsystem_get_next_listener(
 	struct spdk_nvmf_subsystem *subsystem,
@@ -373,8 +425,9 @@ struct spdk_nvmf_listener *spdk_nvmf_subsystem_get_next_listener(
 /**
  * Get a listen address' transport ID
  *
- * \param listener This listener
+ * \param listener This listener.
- * \return The transport ID for this listener
+ *
+ * \return the transport ID for this listener.
  */
 const struct spdk_nvme_transport_id *spdk_nvmf_listener_get_trid(
 	struct spdk_nvmf_listener *listener);
@@ -421,7 +474,7 @@ void spdk_nvmf_ns_opts_get_defaults(struct spdk_nvmf_ns_opts *opts, size_t opts_
  * \param opts Namespace options, or NULL to use defaults.
  * \param opts_size sizeof(*opts)
  *
- * \return Newly added NSID on success or 0 on failure.
+ * \return newly added NSID on success, or 0 on failure.
  */
 uint32_t spdk_nvmf_subsystem_add_ns(struct spdk_nvmf_subsystem *subsystem, struct spdk_bdev *bdev,
 				    const struct spdk_nvmf_ns_opts *opts, size_t opts_size);
@@ -434,24 +487,28 @@ uint32_t spdk_nvmf_subsystem_add_ns(struct spdk_nvmf_subsystem *subsystem, struc
  * \param subsystem Subsystem the namespace belong to.
  * \param nsid Namespace ID to be removed.
  *
- * \return 0 on success or -1 on failure.
+ * \return 0 on success, -1 on failure.
  */
 int spdk_nvmf_subsystem_remove_ns(struct spdk_nvmf_subsystem *subsystem, uint32_t nsid);
 
 /**
- * Return the first allocated namespace in a subsystem.
+ * Get the first allocated namespace in a subsystem.
  *
  * \param subsystem Subsystem to query.
- * \return First allocated namespace in this subsystem, or NULL if this subsystem has no namespaces.
+ *
+ * \return first allocated namespace in this subsystem, or NULL if this subsystem
+ * has no namespaces.
  */
 struct spdk_nvmf_ns *spdk_nvmf_subsystem_get_first_ns(struct spdk_nvmf_subsystem *subsystem);
 
 /**
- * Return the next allocated namespace in a subsystem.
+ * Get the next allocated namespace in a subsystem.
  *
  * \param subsystem Subsystem to query.
  * \param prev_ns Previous ns returned from this function.
- * \return Next allocated namespace in this subsystem, or NULL if prev_ns was the last namespace.
+ *
+ * \return next allocated namespace in this subsystem, or NULL if prev_ns was the
+ * last namespace.
  */
 struct spdk_nvmf_ns *spdk_nvmf_subsystem_get_next_ns(struct spdk_nvmf_subsystem *subsystem,
 		struct spdk_nvmf_ns *prev_ns);
@@ -461,7 +518,8 @@ struct spdk_nvmf_ns *spdk_nvmf_subsystem_get_next_ns(struct spdk_nvmf_subsystem
  *
  * \param subsystem Subsystem to search.
  * \param nsid Namespace ID to find.
- * \return Namespace matching nsid, or NULL if nsid was not found.
+ *
+ * \return namespace matching nsid, or NULL if nsid was not found.
  */
 struct spdk_nvmf_ns *spdk_nvmf_subsystem_get_ns(struct spdk_nvmf_subsystem *subsystem,
 		uint32_t nsid);
@@ -470,6 +528,7 @@ struct spdk_nvmf_ns *spdk_nvmf_subsystem_get_ns(struct spdk_nvmf_subsystem *subs
  * Get a namespace's NSID.
  *
  * \param ns Namespace to query.
+ *
  * \return NSID of ns.
  */
 uint32_t spdk_nvmf_ns_get_id(const struct spdk_nvmf_ns *ns);
@@ -477,8 +536,9 @@ uint32_t spdk_nvmf_ns_get_id(const struct spdk_nvmf_ns *ns);
 /**
  * Get a namespace's associated bdev.
  *
- * \param ns Namespace to query
+ * \param ns Namespace to query.
- * \return Backing bdev of ns.
+ *
+ * \return backing bdev of ns.
  */
 struct spdk_bdev *spdk_nvmf_ns_get_bdev(struct spdk_nvmf_ns *ns);
 
@@ -492,15 +552,56 @@ struct spdk_bdev *spdk_nvmf_ns_get_bdev(struct spdk_nvmf_ns *ns);
 void spdk_nvmf_ns_get_opts(const struct spdk_nvmf_ns *ns, struct spdk_nvmf_ns_opts *opts,
 			   size_t opts_size);
 
+/**
+ * Get the serial number of the specified subsystem.
+ *
+ * \param subsystem Subsystem to query.
+ *
+ * \return serial number of the specified subsystem.
+ */
 const char *spdk_nvmf_subsystem_get_sn(const struct spdk_nvmf_subsystem *subsystem);
 
+
+/**
+ * Set the serial number for the specified subsystem.
+ *
+ * \param subsystem Subsystem to set for.
+ * \param sn serial number to set.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_nvmf_subsystem_set_sn(struct spdk_nvmf_subsystem *subsystem, const char *sn);
 
+/**
+ * Get the NQN of the specified subsystem.
+ *
+ * \param subsystem Subsystem to query.
+ *
+ * \return NQN of the specified subsystem.
+ */
 const char *spdk_nvmf_subsystem_get_nqn(struct spdk_nvmf_subsystem *subsystem);
+
+/**
+ * Get the type of the specified subsystem.
+ *
+ * \param subsystem Subsystem to query.
+ *
+ * \return the type of the specified subsystem.
+ */
 enum spdk_nvmf_subtype spdk_nvmf_subsystem_get_type(struct spdk_nvmf_subsystem *subsystem);
 
+/**
+ * Handle the NVMe-oF request for connection.
+ *
+ * \param req NVMe-oF request to handle.
+ */
 void spdk_nvmf_handle_connect(struct spdk_nvmf_request *req);
 
+/**
+ * Disconnect the NVMe-oF controller.
+ *
+ * \param qpair The NVMe-oF qpair associated with the controller.
+ */
 void spdk_nvmf_ctrlr_disconnect(struct spdk_nvmf_qpair *qpair);
 
 #ifdef __cplusplus