d/numam-spdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

include/nvmf.h: add comments for public APIs

Browse Source 
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>
This commit is contained in:
Yanbo Zhou 2018-02-28 14:27:31 +08:00 committed by Daniel Verkamp
parent b86af2c8d2
commit 5a326bc81a
1 changed files with 164 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
include/spdk/nvmf.h
View File

@ -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