Commit 4dbff01b authored by Yanbo Zhou's avatar Yanbo Zhou Committed by Jim Harris
Browse files

include/io_channel.h: add comments for public APIs 



Change-Id: I85dfac522eb77e5d53fb2fc9c5bb8a75463f1480
Signed-off-by: default avatarYanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/392919


Reviewed-by: default avatarDaniel Verkamp <daniel.verkamp@intel.com>
Tested-by: default avatarSPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: default avatarJim Harris <james.r.harris@intel.com>
parent 63d09e11

include/spdk/io_channel.h

+144 −70
Original line number Diff line number Diff line
@@ -94,16 +94,19 @@ struct spdk_io_channel { 
};



/**

 * \brief Initializes the calling thread for I/O channel allocation.

 * Initializes the calling thread for I/O channel allocation.

 *

 * @param fn A function that may be called from any thread and is

 *          passed a function pointer (spdk_thread_fn) that must be

 *          called on the same thread that spdk_allocate_thread

 * \param msg_fn A function that may be called from any thread and is passed a function

 * pointer (spdk_thread_fn) that must be called on the same thread that spdk_allocate_thread

 * was called from.

 * @param thread_ctx Context that will be passed to fn.

 * @param name Human-readable name for the thread; can be retrieved with spdk_thread_get_name().

 * \param start_poller_fn Function to be called to start a poller for the thread.

 * \param stop_poller_fn Function to be called to stop a poller for the thread.

 * \param thread_ctx Context that will be passed to fn, start_poller_fn and spdk_stop_poller.

 * \param name Human-readable name for the thread; can be retrieved with spdk_thread_get_name().

 * The string is copied, so the pointed-to data only needs to be valid during the

 * spdk_allocate_thread() call. May be NULL to specify no name.

 *

 * \return a pointer to the allocated thread on success or NULL on failure..

 */

struct spdk_thread *spdk_allocate_thread(spdk_thread_pass_msg msg_fn,

		spdk_start_poller start_poller_fn,
@@ -112,7 +115,7 @@ struct spdk_thread *spdk_allocate_thread(spdk_thread_pass_msg msg_fn, 
		const char *name);



/**

 * \brief Releases any resources related to the calling thread for I/O channel allocation.

 * Release any resources related to the calling thread for I/O channel allocation.

 *

 * All I/O channel references related to the calling thread must be released using

 * spdk_put_io_channel() prior to calling this function.
@@ -120,106 +123,138 @@ struct spdk_thread *spdk_allocate_thread(spdk_thread_pass_msg msg_fn, 
void spdk_free_thread(void);



/**

 * \brief Get a handle to the current thread. This handle may be passed

 * to other threads and used as the target of spdk_thread_send_msg().

 * Get a handle to the current thread.

 *

 * This handle may be passed to other threads and used as the target of

 * spdk_thread_send_msg().

 *

 * \sa spdk_io_channel_get_thread()

 *

 * \return a pointer to the current thread on success or NULL on failure.

 */

struct spdk_thread *spdk_get_thread(void);



/**

 * \brief Get a thread's name.

 * Get a thread's name.

 *

 * \param thread Thread to query.

 *

 * \return the name of the thread.

 */

const char *spdk_thread_get_name(const struct spdk_thread *thread);



/**

 * \brief Send a message to the given thread. The message

 * may be sent asynchronously - i.e. spdk_thread_send_msg

 * may return prior to `fn` being called.

 * Send a message to the given thread.

 *

 * @param thread The target thread.

 * @param fn This function will be called on the given thread.

 * @param ctx This context will be passed to fn when called.

 * The message may be sent asynchronously - i.e. spdk_thread_send_msg may return

 * prior to `fn` being called.

 *

 * \param thread The target thread.

 * \param fn This function will be called on the given thread.

 * \param ctx This context will be passed to fn when called.

 */

void spdk_thread_send_msg(const struct spdk_thread *thread, spdk_thread_fn fn, void *ctx);



/**

 * \brief Send a message to each thread, serially. The message

 * is sent asynchronously - i.e. spdk_for_each_thread

 * will return prior to `fn` being called on each thread.

 * Send a message to each thread, serially.

 *

 * The message is sent asynchronously - i.e. spdk_for_each_thread will return

 * prior to `fn` being called on each thread.

 *

 * @param fn This is the function that will be called on each thread.

 * @param ctx This context will be passed to fn when called.

 * @param cpl This will be called on the originating thread after `fn` has been

 * \param fn This is the function that will be called on each thread.

 * \param ctx This context will be passed to fn when called.

 * \param cpl This will be called on the originating thread after `fn` has been

 * called on each thread.

 */

void spdk_for_each_thread(spdk_thread_fn fn, void *ctx, spdk_thread_fn cpl);



/**

 * \brief Register a poller on the current thread. The poller can be

 * unregistered by calling spdk_poller_unregister().

 * Register a poller on the current thread.

 *

 * The poller can be unregistered by calling spdk_poller_unregister().

 *

 * @param fn This function will be called every `period_microseconds`

 * @param arg Passed to fn

 * @param period_microseconds How often to call `fn`. If 0, call `fn` as often as possible.

 * \param fn This function will be called every `period_microseconds`.

 * \param arg Argument passed to fn.

 * \param period_microseconds How often to call `fn`. If 0, call `fn` as often

 *  as possible.

 *

 * \return a pointer to the poller registered on the current thread on success

 * or NULL on failure.

 */

struct spdk_poller *spdk_poller_register(spdk_thread_fn fn,

		void *arg,

		uint64_t period_microseconds);



/**

 * \brief Unregister a poller on the current thread.

 * Unregister a poller on the current thread.

 *

 * @param ppoller The poller to unregister.

 * \param ppoller The poller to unregister.

 */

void spdk_poller_unregister(struct spdk_poller **ppoller);



/**

 * \brief Register the opaque io_device context as an I/O device.

 * Register the opaque io_device context as an I/O device.

 *

 * After an I/O device is registered, it can return I/O channels using the

 *  spdk_get_io_channel() function.  create_cb is the callback function invoked

 *  to allocate any resources required for a new I/O channel.  destroy_cb is the

 *  callback function invoked to release the resources for an I/O channel.  ctx_size

 *  is the size of the context buffer allocated to store references to allocated I/O

 *  channel resources.

 * spdk_get_io_channel() function.

 *

 * \param io_device The pointer to io_device context.

 * \param create_cb Callback function invoked to allocate any resources required

 * for a new I/O channel.

 * \param destroy_cb Callback function invoked to release the resources for an

 * I/O channel.

 * \param ctx_size The size of the context buffer allocated to store references

 * to allocated I/O channel resources.

 */

void spdk_io_device_register(void *io_device, spdk_io_channel_create_cb create_cb,

			     spdk_io_channel_destroy_cb destroy_cb, uint32_t ctx_size);



/**

 * \brief Unregister the opaque io_device context as an I/O device.

 * Unregister the opaque io_device context as an I/O device.

 *

 * The actual unregistration might be deferred until all active I/O channels are destroyed.

 *  unregister_cb is an optional callback function invoked to release any references to

 *  this I/O device.

 * The actual unregistration might be deferred until all active I/O channels are

 * destroyed.

 *

 * \param io_device The pointer to io_device context.

 * \param unregister_cb An optional callback function invoked to release any

 * references to this I/O device.

 */

void spdk_io_device_unregister(void *io_device, spdk_io_device_unregister_cb unregister_cb);



/**

 * \brief Gets an I/O channel for the specified io_device to be used by the calling thread.

 *

 * The io_device context pointer specified must have previously been registered using

 *  spdk_io_device_register().  If an existing I/O channel does not exist yet for the given

 *  io_device on the calling thread, it will allocate an I/O channel and invoke the create_cb

 *  function pointer specified in spdk_io_device_register().  If an I/O channel already

 *  exists for the given io_device on the calling thread, its reference is returned rather

 *  than creating a new I/O channel.

 * Get an I/O channel for the specified io_device to be used by the calling thread.

 *

 * The io_device context pointer specified must have previously been registered

 * using spdk_io_device_register(). If an existing I/O channel does not exist

 * yet for the given io_device on the calling thread, it will allocate an I/O

 * channel and invoke the create_cb function pointer specified in spdk_io_device_register().

 * If an I/O channel already exists for the given io_device on the calling thread,

 * its reference is returned rather than creating a new I/O channel.

 *

 * \param io_device The pointer to io_device context.

 *

 * \return a pointer to the I/O channel for this device on success or NULL on failure.

 */

struct spdk_io_channel *spdk_get_io_channel(void *io_device);



/**

 * \brief Releases a reference to an I/O channel. This happens asynchronously.

 * Release a reference to an I/O channel. This happens asynchronously.

 *

 * Actual release will happen on the same thread that called spdk_get_io_channel()

 * for the specified I/O channel. If this releases the last reference to the

 * I/O channel, The destroy_cb function specified in spdk_io_device_register()

 * will be invoked to release any associated resources.

 *

 * Actual release will happen on the same thread that called spdk_get_io_channel() for the

 *  specified I/O channel.  If this releases the last reference to the I/O channel, The

 *  destroy_cb function specified in spdk_io_device_register() will be invoked to release

 *  any associated resources.

 * \param ch I/O channel to release a reference.

 */

void spdk_put_io_channel(struct spdk_io_channel *ch);



/**

 * \brief Returns the context buffer associated with an I/O channel.

 * Get the context buffer associated with an I/O channel.

 *

 * \param ch I/O channel.

 *

 * \return a pointer to the context buffer.

 */

static inline void *

spdk_io_channel_get_ctx(struct spdk_io_channel *ch)
@@ -228,36 +263,75 @@ spdk_io_channel_get_ctx(struct spdk_io_channel *ch) 
}



/**

 *  \brief Returns an I/O channel from a context buffer. This is

 * the inverse of spdk_io_channel_get_ctx().

 * Get I/O channel from the context buffer. This is the inverse of

 * spdk_io_channel_get_ctx().

 *

 * \param ctx The pointer to the context buffer.

 *

 * \return a pointer to the I/O channel associated with the context buffer.

 */

struct spdk_io_channel *spdk_io_channel_from_ctx(void *ctx);



/**

 * \brief Returns the spdk_thread associated with an I/O channel.

 * Get the thread associated with an I/O channel.

 *

 * \param ch I/O channel.

 *

 * \return a pointer to the thread associated with the I/O channel

 */

struct spdk_thread *spdk_io_channel_get_thread(struct spdk_io_channel *ch);



/**

 * \brief Call 'fn' on each channel associated with io_device. This happens

 * asynchronously, so fn may be called after spdk_for_each_channel returns.

 * 'fn' will be called on the correct thread for each channel. 'fn' will be

 * called for each channel serially, such that two calls to 'fn' will not

 * overlap in time. After 'fn' has been called, call

 * Call 'fn' on each channel associated with io_device.

 *

 * This happens asynchronously, so fn may be called after spdk_for_each_channel

 * returns. 'fn' will be called for each channel serially, such that two calls

 * to 'fn' will not overlap in time. After 'fn' has been called, call

 * spdk_for_each_channel_continue() to continue iterating.

 *

 * Once 'fn' has been called on each channel, 'cpl' will be called

 * on the thread that spdk_for_each_channel was initially called from.

 * \param io_device 'fn' will be called on each channel associated with this io_device.

 * \param fn Called on the appropriate thread for each channel associated with io_device.

 * \param ctx Context buffer registered to spdk_io_channel_iter that can be obatined

 * form the function spdk_io_channel_iter_get_ctx().

 * \param cpl Called on the thread that spdk_for_each_channel was initially called

 * from when 'fn' has been called on each channel.

 */

void spdk_for_each_channel(void *io_device, spdk_channel_msg fn, void *ctx,

			   spdk_channel_for_each_cpl cpl);



/**

 * Get io_device from the I/O channel iterator.

 *

 * \param i I/O channel iterator.

 *

 * \return a pointer to the io_device.

 */

void *spdk_io_channel_iter_get_io_device(struct spdk_io_channel_iter *i);



/**

 * Get I/O channel from the I/O channel iterator.

 *

 * \param i I/O channel iterator.

 *

 * \return a pointer to the I/O channel.

 */

struct spdk_io_channel *spdk_io_channel_iter_get_channel(struct spdk_io_channel_iter *i);



/**

 * Get context buffer from the I/O channel iterator.

 *

 * \param i I/O channel iterator.

 *

 * \return a pointer to the context buffer.

 */

void *spdk_io_channel_iter_get_ctx(struct spdk_io_channel_iter *i);



/**

 * Helper function to iterate all channels for spdk_for_each_channel().

 *

 * \param i I/O channel iterator.

 * \param status Status for the I/O channel iterator.

 */

void spdk_for_each_channel_continue(struct spdk_io_channel_iter *i, int status);



#ifdef __cplusplus