From 4dbff01ba3c978a315569721a3eeb3480c266cc2 Mon Sep 17 00:00:00 2001 From: Yanbo Zhou Date: Mon, 25 Dec 2017 16:33:25 +0800 Subject: [PATCH] include/io_channel.h: add comments for public APIs Change-Id: I85dfac522eb77e5d53fb2fc9c5bb8a75463f1480 Signed-off-by: Yanbo Zhou Reviewed-on: https://review.gerrithub.io/392919 Reviewed-by: Daniel Verkamp Tested-by: SPDK Automated Test System Reviewed-by: Jim Harris --- include/spdk/io_channel.h | 208 ++++++++++++++++++++++++++------------ 1 file changed, 141 insertions(+), 67 deletions(-) diff --git a/include/spdk/io_channel.h b/include/spdk/io_channel.h index 821ed4eaa..81e2402f8 100644 --- a/include/spdk/io_channel.h +++ b/include/spdk/io_channel.h @@ -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 - * 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(). - * 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. + * \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 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,114 +115,146 @@ 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. + * spdk_put_io_channel() prior to calling this function. */ 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. * - * @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. + * 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 + * 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. * - * @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. + * The poller can be unregistered by calling spdk_poller_unregister(). + * + * \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. + * 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. + * 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