include/nvmf.h: add comments for public APIs

	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.

 */

 * 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);

 * 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);

 * \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,

 * \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,

 * \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,

 * \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,

 * \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);

 *

 * 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);

 *

 * 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);

 * 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);

 * 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);

 *

 * 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,

/**

 * 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);

 * \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);

 * \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);

 *

 * \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);

 * 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);

/**

 * 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);

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