From 5a326bc81a8eb243775646fb5f3c2f57d9e2ff71 Mon Sep 17 00:00:00 2001 From: Yanbo Zhou Date: Wed, 28 Feb 2018 14:27:31 +0800 Subject: [PATCH] include/nvmf.h: add comments for public APIs Change-Id: Ie921c78f09842f9c8d008cc18a4c7145b458b559 Signed-off-by: Yanbo Zhou Reviewed-on: https://review.gerrithub.io/401782 Reviewed-by: GangCao Tested-by: SPDK Automated Test System Reviewed-by: Changpeng Liu Reviewed-by: Daniel Verkamp --- include/spdk/nvmf.h | 227 ++++++++++++++++++++++++++++++++------------ 1 file changed, 164 insertions(+), 63 deletions(-) diff --git a/include/spdk/nvmf.h b/include/spdk/nvmf.h index d33373c9c4..14a3263568 100644 --- a/include/spdk/nvmf.h +++ b/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 - * \return An spdk_nvmf_tgt on success, NULL on failure. + * \param opts Options. + * + * \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 trid The address to listen at + * \param tgt The target associated with this listen address. + * \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 - * will only be called on success. + * \return 0 on success, or negated errno on failure. The callback provided will only + * 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 - * will only be called on success. + * \return 0 on success, or negated errno on failure. The callback provided will only + * 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 - * will only be called on success. + * \return 0 on success, or negated errno on failure. The callback provided will only + * 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 - * will only be called on success. + * \return 0 on success, or negated errno on failure. The callback provided will only + * 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 host_nqn The NQN for the host - * \return 0 on success. Negated errno value on failure. + * \param subsystem Subsystem to add host to. + * \param host_nqn The NQN for the host. + * + * \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 host_nqn The NQN for the host - * \return 0 on success. Negated errno value on failure. + * \param subsystem Subsystem to remove host from. + * \param host_nqn The NQN for the host. + * + * \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 - * the whitelist configured with spdk_nvmf_subsystem_add_host(). - * \return 0 on success. Negated errno value on failure. + * \param allow_any_host true to allow any host to connect to this subsystem, + * or false to enforce the whitelist configured with spdk_nvmf_subsystem_add_host(). + * + * \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 hostnqn The NQN of the host + * \param subsystem The subsystem to query. + * \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 trid The address to accept connections from - * \return 0 on success. Negated errno value on failure. + * \param subsystem Subsystem to add listener to. + * \param trid The address to accept connections from. + * + * \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 trid The address to no longer accept connections from - * \return 0 on success. Negated errno value on failure. + * \param subsystem Subsystem to remove listener from. + * \param trid The address to no longer accept connections from. + * + * \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 trid The listen address - * \return true if allowed, false if not. + * \param subsystem The subsystem to query. + * \param trid The listen address. + * + * \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 - * \return Next allowed listen address in this subsystem, or NULL if prev_listener was the last address. + * \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. */ 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 - * \return The transport ID for this listener + * \param listener 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 - * \return Backing bdev of ns. + * \param ns Namespace to query. + * + * \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