diff --git a/CHANGELOG.md b/CHANGELOG.md index c7954a754..96d6c0c23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ SPDK has switched to DPDK's rte_vhost library since 19.07 release, removed the i rte_vhost library which is used for DPDK older than 19.05, removed the experimental vhost nvme target which depends on the internal rte_vhost library. +### util + +A new utility named `fd_group` was add. It is now +implemented by epoll on Linux platform. It can be used by +spdk_thread and reactor to implement interrupt mode. + ### bdev A new `spdk_bdev_part_base_construct_ext` function has been added and the diff --git a/include/spdk/fd_group.h b/include/spdk/fd_group.h new file mode 100644 index 000000000..3a16ab5cd --- /dev/null +++ b/include/spdk/fd_group.h @@ -0,0 +1,145 @@ +/*- + * BSD LICENSE + * + * Copyright (c) Intel Corporation. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Intel Corporation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * \file + * File descriptor group utility functions + */ + +#ifndef SPDK_FD_GROUP_H +#define SPDK_FD_GROUP_H + +#include "spdk/stdinc.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Callback function registered for the event source file descriptor. + * + * \param ctx Context passed as arg to spdk_fd_group_add(). + * + * \return 0 to indicate that event notification took place but no events were found; + * positive to indicate that event notification took place and some events were processed; + * negative if no event information is provided. + */ +typedef int (*spdk_fd_fn)(void *ctx); + +/** + * A file descriptor group of event sources which gather the events to an epoll instance. + * + * Taking "fgrp" as short name for file descriptor group of event sources. + */ +struct spdk_fd_group; + +/** + * Initialize one fd_group. + * + * \param fgrp A pointer to return the initialized fgrp. + * + * \return 0 if success or -errno if failed + */ +int spdk_fd_group_create(struct spdk_fd_group **fgrp); + +/** + * Release all resources associated with this fgrp. + * + * Users need to remove all event sources from the fgrp before destroying it. + * + * \param fgrp The fgrp to destroy. + */ +void spdk_fd_group_destroy(struct spdk_fd_group *fgrp); + +/** + * Wait for new events generated inside fgrp, and process them with their + * registered spdk_fd_fn. + * + * \param fgrp The fgrp to wait and process. + * \param timeout Specifies the number of milliseconds that will block. + * -1 causes indefinitedly blocking; 0 causes immediately return. + * + * \return 0 if any events get processed + * or -errno if failed + */ +int spdk_fd_group_wait(struct spdk_fd_group *fgrp, int timeout); + +/** + * Return the internal epoll_fd of specific fd_group + * + * \param fgrp The pointer of specified fgrp. + * + * \return The epoll_fd of specific fgrp. + */ +int spdk_fd_group_get_fd(struct spdk_fd_group *fgrp); + +/** + * Register one event source to specified fgrp. + * + * \param fgrp The fgrp registered to. + * \param efd File descriptor of the event source. + * \param fn Called each time there are events in event source. + * \param arg Function argument for fn. + * + * \return 0 if success or -errno if failed + */ +int spdk_fd_group_add(struct spdk_fd_group *fgrp, + int efd, spdk_fd_fn fn, void *arg); + +/** + * Unregister one event source from one fgrp. + * + * \param fgrp The fgrp registered to. + * \param efd File descriptor of the event source. + */ +void spdk_fd_group_remove(struct spdk_fd_group *fgrp, int efd); + +/** + * Change the event notification types associated with the event source. + * + * Modules like nbd, need this api to add EPOLLOUT when having data to send, and remove EPOLLOUT if no data to send. + * + * \param fgrp The fgrp registered to. + * \param efd File descriptor of the event source. + * \param event_types The event notification types. + * + * \return 0 if success or -errno if failed + */ +int spdk_fd_group_event_modify(struct spdk_fd_group *fgrp, + int efd, int event_types); + +#ifdef __cplusplus +} +#endif + +#endif /* SPDK_FD_GROUP_H */ diff --git a/lib/util/Makefile b/lib/util/Makefile index cfacef242..b8a0cb525 100644 --- a/lib/util/Makefile +++ b/lib/util/Makefile @@ -38,7 +38,8 @@ SO_VER := 2 SO_MINOR := 1 C_SRCS = base64.c bit_array.c cpuset.c crc16.c crc32.c crc32c.c crc32_ieee.c \ - dif.c fd.c file.c iov.c math.c pipe.c strerror_tls.c string.c uuid.c + dif.c fd.c file.c iov.c math.c pipe.c strerror_tls.c string.c uuid.c \ + fd_group.c LIBNAME = util LOCAL_SYS_LIBS = -luuid diff --git a/lib/util/fd_group.c b/lib/util/fd_group.c new file mode 100644 index 000000000..c16e3d66c --- /dev/null +++ b/lib/util/fd_group.c @@ -0,0 +1,351 @@ +/*- + * BSD LICENSE + * + * Copyright(c) Intel Corporation. All rights reserved. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Intel Corporation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include "spdk/queue.h" +#include "spdk/log.h" +#include "spdk/fd_group.h" + +#ifdef __linux__ +#include +#endif + +enum event_handler_state { + /* The event_handler is added into an fd_group waiting for event, + * but not currently in the execution of a wait loop. + */ + EVENT_HANDLER_STATE_WAITING, + + /* The event_handler is currently in the execution of a wait loop. */ + EVENT_HANDLER_STATE_RUNNING, + + /* The event_handler was removed during the execution of a wait loop. */ + EVENT_HANDLER_STATE_REMOVED, +}; + +/* file descriptor of the interrupt event */ + +/* Taking "ehdlr" as short name for file descriptor handler of the interrupt event. */ +struct event_handler { + TAILQ_ENTRY(event_handler) next; + enum event_handler_state state; + + spdk_fd_fn fn; + void *fn_arg; + /* file descriptor of the interrupt event */ + int fd; +}; + +struct spdk_fd_group { + int epfd; + int num_fds; /* Number of fds registered in this group. */ + + /* interrupt sources list */ + TAILQ_HEAD(, event_handler) event_handlers; +}; + +int +spdk_fd_group_get_fd(struct spdk_fd_group *fgrp) +{ + return fgrp->epfd; +} + +#ifdef __linux__ + +int +spdk_fd_group_add(struct spdk_fd_group *fgrp, + int efd, spdk_fd_fn fn, void *arg) +{ + struct event_handler *ehdlr; + struct epoll_event epevent; + int rc; + + /* parameter checking */ + if (fgrp == NULL || efd <= 0 || fn == NULL) { + return -EINVAL; + } + + /* check if there is already one function registered for this fd */ + TAILQ_FOREACH(ehdlr, &fgrp->event_handlers, next) { + if (ehdlr->fd == efd) { + return -EEXIST; + } + } + + /* create a new event src */ + ehdlr = calloc(1, sizeof(*ehdlr)); + if (ehdlr == NULL) { + return -errno; + } + + ehdlr->fd = efd; + ehdlr->fn = fn; + ehdlr->fn_arg = arg; + ehdlr->state = EVENT_HANDLER_STATE_WAITING; + + epevent.events = EPOLLIN; + epevent.data.ptr = ehdlr; + rc = epoll_ctl(fgrp->epfd, EPOLL_CTL_ADD, efd, &epevent); + if (rc < 0) { + free(ehdlr); + return -errno; + } + + TAILQ_INSERT_TAIL(&fgrp->event_handlers, ehdlr, next); + fgrp->num_fds++; + + return 0; +} + +void +spdk_fd_group_remove(struct spdk_fd_group *fgrp, int efd) +{ + struct event_handler *ehdlr; + int rc; + + if (fgrp == NULL || efd <= 0) { + SPDK_ERRLOG("Invalid to remvoe efd(%d) from fd_group(%p).\n", efd, fgrp); + assert(0); + return; + } + + + TAILQ_FOREACH(ehdlr, &fgrp->event_handlers, next) { + if (ehdlr->fd == efd) { + break; + } + } + + if (ehdlr == NULL) { + SPDK_ERRLOG("efd(%d) is not existed in fgrp(%p)\n", efd, fgrp); + return; + } + + assert(ehdlr->state != EVENT_HANDLER_STATE_REMOVED); + + rc = epoll_ctl(fgrp->epfd, EPOLL_CTL_DEL, ehdlr->fd, NULL); + if (rc < 0) { + SPDK_ERRLOG("Failed to delete the fd(%d) from the epoll group(%p)\n", efd, fgrp); + return; + } + + assert(fgrp->num_fds > 0); + fgrp->num_fds--; + TAILQ_REMOVE(&fgrp->event_handlers, ehdlr, next); + + /* Delay ehdlr's free in case it is waiting for execution in fgrp wait loop */ + if (ehdlr->state == EVENT_HANDLER_STATE_RUNNING) { + ehdlr->state = EVENT_HANDLER_STATE_REMOVED; + } else { + free(ehdlr); + } +} + +int +spdk_fd_group_event_modify(struct spdk_fd_group *fgrp, + int efd, int event_types) +{ + struct epoll_event epevent; + struct event_handler *ehdlr; + + if (fgrp == NULL || efd <= 0) { + return -EINVAL; + } + + TAILQ_FOREACH(ehdlr, &fgrp->event_handlers, next) { + if (ehdlr->fd == efd) { + break; + } + } + + if (ehdlr == NULL) { + return -EINVAL; + } + + assert(ehdlr->state != EVENT_HANDLER_STATE_REMOVED); + + epevent.events = event_types; + epevent.data.ptr = ehdlr; + + return epoll_ctl(fgrp->epfd, EPOLL_CTL_MOD, ehdlr->fd, &epevent); +} + +int +spdk_fd_group_create(struct spdk_fd_group **_egrp) +{ + struct spdk_fd_group *fgrp; + + if (_egrp == NULL) { + return -EINVAL; + } + + fgrp = calloc(1, sizeof(*fgrp)); + if (fgrp == NULL) { + return -ENOMEM; + } + + /* init the event source head */ + TAILQ_INIT(&fgrp->event_handlers); + + fgrp->num_fds = 0; + fgrp->epfd = epoll_create1(EPOLL_CLOEXEC); + if (fgrp->epfd < 0) { + free(fgrp); + return -errno; + } + + *_egrp = fgrp; + + return 0; +} + +void +spdk_fd_group_destroy(struct spdk_fd_group *fgrp) +{ + if (fgrp == NULL || fgrp->num_fds > 0) { + SPDK_ERRLOG("Invalid fd_group(%p) to destroy.\n", fgrp); + assert(0); + return; + } + + close(fgrp->epfd); + free(fgrp); + + return; +} + +int +spdk_fd_group_wait(struct spdk_fd_group *fgrp, int timeout) +{ + int totalfds = fgrp->num_fds; + struct epoll_event events[totalfds]; + struct event_handler *ehdlr; + int n; + int nfds; + + nfds = epoll_wait(fgrp->epfd, events, totalfds, timeout); + if (nfds < 0) { + if (errno != EINTR) { + SPDK_ERRLOG("fgrp epoll_wait returns with fail. errno is %d\n", errno); + } + + return -errno; + } else if (nfds == 0) { + return 0; + } + + for (n = 0; n < nfds; n++) { + /* find the event_handler */ + ehdlr = events[n].data.ptr; + + if (ehdlr == NULL) { + continue; + } + + /* Tag ehdlr as running state in case that it is removed + * during this wait loop but before or when it get executed. + */ + assert(ehdlr->state == EVENT_HANDLER_STATE_WAITING); + ehdlr->state = EVENT_HANDLER_STATE_RUNNING; + } + + for (n = 0; n < nfds; n++) { + /* find the event_handler */ + ehdlr = events[n].data.ptr; + + if (ehdlr == NULL || ehdlr->fn == NULL) { + continue; + } + + /* It is possible that the ehdlr was removed + * during this wait loop but before it get executed. + */ + if (ehdlr->state == EVENT_HANDLER_STATE_REMOVED) { + free(ehdlr); + continue; + } + + /* call the interrupt response function */ + ehdlr->fn(ehdlr->fn_arg); + + /* It is possible that the ehdlr was removed + * during this wait loop when it get executed. + */ + if (ehdlr->state == EVENT_HANDLER_STATE_REMOVED) { + free(ehdlr); + } else { + ehdlr->state = EVENT_HANDLER_STATE_WAITING; + } + } + + return nfds; +} + +#else + +int +spdk_fd_group_add(struct spdk_fd_group *fgrp, + int efd, spdk_fd_fn fn, void *arg) +{ + return -ENOTSUP; +} + +void +spdk_fd_group_remove(struct spdk_fd_group *fgrp, int efd) +{ +} + +int +spdk_fd_group_event_modify(struct spdk_fd_group *fgrp, + int efd, int event_types) +{ + return -ENOTSUP; +} + +int +spdk_fd_group_create(struct spdk_fd_group **fgrp) +{ + return -ENOTSUP; +} + +void +spdk_fd_group_destroy(struct spdk_fd_group *fgrp) +{ +} + +int +spdk_fd_group_wait(struct spdk_fd_group *fgrp, int timeout) +{ + return -ENOTSUP; +} + +#endif diff --git a/lib/util/spdk_util.map b/lib/util/spdk_util.map index 118f7511d..31b191af0 100644 --- a/lib/util/spdk_util.map +++ b/lib/util/spdk_util.map @@ -135,9 +135,14 @@ spdk_uuid_generate; spdk_uuid_copy; - - - + # public functions in fd_group.h + spdk_fd_group_create; + spdk_fd_group_destroy; + spdk_fd_group_wait; + spdk_fd_group_add; + spdk_fd_group_remove; + spdk_fd_group_event_modify; + spdk_fd_group_get_fd; local: *; };