Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/86507/?format=api
{ "id": 86507, "url": "https://patches.dpdk.org/api/patches/86507/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20210114061411.39166-10-chenbo.xia@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20210114061411.39166-10-chenbo.xia@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20210114061411.39166-10-chenbo.xia@intel.com", "date": "2021-01-14T06:14:11", "name": "[v2,9/9] doc: add vfio-user library guide", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": true, "hash": "94e1ba35e14ae869391659b6bf2b413fe5b72c97", "submitter": { "id": 1276, "url": "https://patches.dpdk.org/api/people/1276/?format=api", "name": "Chenbo Xia", "email": "chenbo.xia@intel.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20210114061411.39166-10-chenbo.xia@intel.com/mbox/", "series": [ { "id": 14711, "url": "https://patches.dpdk.org/api/series/14711/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=14711", "date": "2021-01-14T06:14:02", "name": "Introduce vfio-user library", "version": 2, "mbox": "https://patches.dpdk.org/series/14711/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/86507/comments/", "check": "fail", "checks": "https://patches.dpdk.org/api/patches/86507/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 945C9A0A02;\n\tThu, 14 Jan 2021 07:21:06 +0100 (CET)", "from [217.70.189.124] (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 8254F140DB2;\n\tThu, 14 Jan 2021 07:20:08 +0100 (CET)", "from mga06.intel.com (mga06.intel.com [134.134.136.31])\n by mails.dpdk.org (Postfix) with ESMTP id D2E33140DB2\n for <dev@dpdk.org>; Thu, 14 Jan 2021 07:20:05 +0100 (CET)", "from orsmga003.jf.intel.com ([10.7.209.27])\n by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 13 Jan 2021 22:20:02 -0800", "from npg-dpdk-virtio-xiachenbo-nw.sh.intel.com ([10.67.119.123])\n by orsmga003.jf.intel.com with ESMTP; 13 Jan 2021 22:19:57 -0800" ], "IronPort-SDR": [ "\n oQmfWp/pZ90xkq4QoNcLAw0NlTK/4UlTapMewdbCiJjFqpQdom0yliVxl1jcvlKqY0kLBvjupN\n lxsIwi++zd4A==", "\n pI3ivEaqYgaPXroplMkbDJQ2K2ITCd6L7aETUqD5Wja5m80I6SGsemvRijmYO7PN65PzvnZW2j\n yVak8UwT3XWQ==" ], "X-IronPort-AV": [ "E=McAfee;i=\"6000,8403,9863\"; a=\"239856372\"", "E=Sophos;i=\"5.79,346,1602572400\"; d=\"scan'208\";a=\"239856372\"", "E=Sophos;i=\"5.79,346,1602572400\"; d=\"scan'208\";a=\"349069075\"" ], "X-ExtLoop1": "1", "From": "Chenbo Xia <chenbo.xia@intel.com>", "To": "dev@dpdk.org,\n\tthomas@monjalon.net,\n\tdavid.marchand@redhat.com", "Cc": "stephen@networkplumber.org, cunming.liang@intel.com, xiuchun.lu@intel.com,\n miao.li@intel.com, jingjing.wu@intel.com, beilei.xing@intel.com", "Date": "Thu, 14 Jan 2021 14:14:11 +0800", "Message-Id": "<20210114061411.39166-10-chenbo.xia@intel.com>", "X-Mailer": "git-send-email 2.17.1", "In-Reply-To": "<20210114061411.39166-1-chenbo.xia@intel.com>", "References": "<20201218073851.93609-1-chenbo.xia@intel.com>\n <20210114061411.39166-1-chenbo.xia@intel.com>", "Subject": "[dpdk-dev] [PATCH v2 9/9] doc: add vfio-user library guide", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Add vfio-user library guide and update release notes.\n\nSigned-off-by: Chenbo Xia <chenbo.xia@intel.com>\nSigned-off-by: Xiuchun Lu <xiuchun.lu@intel.com>\n---\n doc/guides/prog_guide/index.rst | 1 +\n doc/guides/prog_guide/vfio_user_lib.rst | 215 ++++++++++++++++++++++++\n doc/guides/rel_notes/release_21_02.rst | 11 ++\n 3 files changed, 227 insertions(+)\n create mode 100644 doc/guides/prog_guide/vfio_user_lib.rst", "diff": "diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst\nindex 45c7dec88d..f9847b1058 100644\n--- a/doc/guides/prog_guide/index.rst\n+++ b/doc/guides/prog_guide/index.rst\n@@ -70,3 +70,4 @@ Programmer's Guide\n lto\n profile_app\n glossary\n+ vfio_user_lib\ndiff --git a/doc/guides/prog_guide/vfio_user_lib.rst b/doc/guides/prog_guide/vfio_user_lib.rst\nnew file mode 100644\nindex 0000000000..5ef9e2f2b0\n--- /dev/null\n+++ b/doc/guides/prog_guide/vfio_user_lib.rst\n@@ -0,0 +1,215 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2020 Intel Corporation.\n+\n+Vfio User Library\n+=============\n+\n+The vfio-user library implements the vfio-user protocol, which is a protocol\n+that allows an I/O device to be emulated in a separate process outside of a\n+Virtual Machine Monitor (VMM). The protocol has a client/server model, in which\n+the server emulates the device and the client (e.g., VMM) consumes the device.\n+Vfio-user library uses the device model of Linux kernel VFIO and core concepts\n+defined in its API. The main difference between kernel VFIO and vfio-user is\n+that the device consumer uses messages over a UNIX domain socket instead of\n+system calls in vfio-user.\n+\n+The vfio-user library is used to construct and consume emulated devices. The\n+server side implementation is mainly for construction of devices and the client\n+side implementation is mainly for consumption and manipulation of devices. You\n+use server APIs mainly for two things: provide the device information (e.g.,\n+region/irq information) to vfio-user library and acquire the configuration\n+(e.g., DMA table) from client. To construct a device, you could only focus on\n+the device abstraction that vfio-user library defines rather than how the\n+server side communicated with client. You use client APIs mainly for acquiring\n+the device information and configuring the device. The client API usage is\n+almost the same as the kernel VFIO ioctl.\n+\n+\n+Vfio User Server API Overview\n+------------------\n+\n+The following is an overview of key Vfio User Server API functions. You will\n+know how to build an emulated device with this overview.\n+\n+There are mainly four steps of using Vfio User API to build your device:\n+\n+1. Register\n+\n+This step includes one API in Vfio User.\n+\n+* ``rte_vfio_user_register(sock_addr, notify_ops)``\n+\n+ This function registers a session to communicate with vfio-user client. A\n+ session maps to one device so that a device instance will be created upon\n+ registration.\n+\n+ ``sock_addr`` specifies the Unix domain socket file path and is the identity\n+ of the session.\n+\n+ ``notify_ops`` is the a set of callbacks for vfio-user library to notify\n+ emulated device. Currently, there are five callbacks:\n+\n+ - ``new_device``\n+ This callback is invoked when the device is configured and becomes ready.\n+ The dev_id is for vfio-user library to identify one uniqueue device.\n+\n+ - ``destroy_device``\n+ This callback is invoked when the device is destroyed. In most cases, it\n+ means the client is disconnected from the server.\n+\n+ - ``update_status``\n+ This callback is invoked when the device configuration is updated (e.g.,\n+ DMA table/IRQ update)\n+\n+ - ``lock_dp``\n+ This callback is invoked when data path needs to be locked or unlocked.\n+\n+ - ``reset_device``\n+ This callback is invoked when the emulated device need reset.\n+\n+2. Set device information\n+\n+This step includes three APIs in Vfio User.\n+\n+* ``rte_vfio_user_set_dev_info(sock_addr, dev_info)``\n+\n+ This function sets the device information to vfio-user library. The device\n+ information is defined in Linux VFIO which mainly consists of device type\n+ and the number of vfio regions and IRQs.\n+\n+* ``rte_vfio_user_set_reg_info(sock_addr, reg)``\n+\n+ This function sets the vfio region information to vfio-user library. Regions\n+ should be created before using this API. The information mainly includes the\n+ process virtual address, size, file descriptor, attibutes and capabilities of\n+ regions.\n+\n+* ``rte_vfio_user_set_irq_info(sock_addr, irq)``\n+\n+ This function sets the IRQ information to vfio-user library. The information\n+ includes how many IRQ type the device supports (e.g., MSI/MSI-X) and the IRQ\n+ count of each type.\n+\n+3. Start\n+\n+This step includes one API in Vfio User.\n+\n+* ``rte_vfio_user_start(sock_addr)``\n+\n+ This function starts the registered session with vfio-user client. This means\n+ a control thread will start to listen and handle messages sent from the client.\n+ Note that only one thread is created for all vfio-user based devices.\n+\n+ ``sock_addr`` specifies the Unix domain socket file path and is the identity\n+ of the session.\n+\n+4. Get device configuration\n+\n+This step includes two APIs in Vfio User. Both APIs should be called when the\n+device is ready could be updated anytime. A simple usage of both APIs is using\n+them in new_device and update_status callbacks.\n+\n+* ``rte_vfio_user_get_mem_table(dev_id)``\n+\n+ This function gets the DMA memory table from vfio-user library. The memory\n+ table entry has the information of guest physical address, process virtual\n+ address, size and file descriptor. Emulated devices could use the memory\n+ table to perform DMA read/write on guest memory.\n+\n+ ``dev_id`` specifies the device ID.\n+\n+* ``rte_vfio_user_get_irq(dev_id, index, count, fds)``\n+\n+ This function gets the IRQ's eventfd from vfio-user library. In vfio-user\n+ library, an efficient way to send interrupts is using eventfds. The eventfd\n+ should be sent from client. Emulated devices could only call eventfd_write\n+ to trigger interrupts.\n+\n+ ``dev_id`` specifies the device ID.\n+\n+ ``index`` specifies the interrupt type. The mapping of interrupt index and\n+ type is defined by emulated device.\n+\n+ ``count`` specifies the interrupt count.\n+\n+ ``fds`` is for saving the file descriptors.\n+\n+\n+Vfio User Client API Overview\n+------------------\n+\n+The following is an overview of key Vfio User Client API functions. You will\n+know how to use an emulated device with this overview.\n+\n+There are mainly three steps of using Vfio User Client API to consume the\n+device:\n+\n+1. Attach\n+\n+This step includes one API in Vfio User.\n+\n+* ``rte_vfio_user_attach_dev(sock_addr)``\n+\n+ This function attaches to an emulated device. After the function call\n+ success, it is viable to acquire device information and configure the device\n+\n+ ``sock_addr`` specifies the Unix domain socket file path and is the identity\n+ of the session/device.\n+\n+2. Get device information\n+\n+This step includes three APIs in Vfio User.\n+\n+* ``rte_vfio_user_get_dev_info(dev_id, info)``\n+\n+ This function gets the device information of the emulated device on the other\n+ side of socket. The device information is defined in Linux VFIO which mainly\n+ consists of device type and the number of vfio regions and IRQs.\n+\n+ ``dev_id`` specifies the identity of the device.\n+\n+ ``info`` specifies the information of the device.\n+\n+* ``rte_vfio_user_get_reg_info(dev_id, info, fd)``\n+\n+ This function gets the region information of the emulated device on the other\n+ side of socket. The region information is defined in Linux VFIO which mainly\n+ consists of region size, index and capabilities.\n+\n+ ``info`` specifies the information of the region.\n+\n+ ``fd`` specifies the file descriptor of the region.\n+\n+* ``rte_vfio_user_get_irq_info(dev_id, irq)``\n+\n+ This function sets the IRQ information to vfio-user library. The IRQ\n+ information includes IRQ count and index.\n+\n+ ``info`` specifies the information of the IRQ.\n+\n+3. Configure the device\n+\n+This step includes three APIs in Vfio User.\n+\n+* ``rte_vfio_user_dma_map(dev_id, mem, fds, num)``\n+\n+ This function maps DMA memory regions for the emulated device.\n+\n+ ``mem`` specifies the information of DMA memory regions.\n+\n+ ``fds`` specifies the file descriptors of the DMA memory regions.\n+\n+ ``num`` specifies the number of the DMA memory regions.\n+\n+* ``rte_vfio_user_dma_unmap(dev_id, mem, num)``\n+\n+ This function unmaps DMA memory regions for the emulated device.\n+\n+* ``rte_vfio_user_set_irqs(dev_id, set)``\n+\n+ This function configure the interrupts for the emulated device.\n+\n+ ``set`` specifies the configuration of interrupts.\n+\n+After the above three steps are done, users can easily use the emulated device\n+(e.g., do I/O operations).\n\\ No newline at end of file\ndiff --git a/doc/guides/rel_notes/release_21_02.rst b/doc/guides/rel_notes/release_21_02.rst\nindex 706cbf8f0c..eabbbfebef 100644\n--- a/doc/guides/rel_notes/release_21_02.rst\n+++ b/doc/guides/rel_notes/release_21_02.rst\n@@ -55,6 +55,17 @@ New Features\n Also, make sure to start the actual text at the margin.\n =======================================================\n \n+* **Added vfio-user Library.**\n+\n+ Added an experimental library ``librte_vfio_user`` to provide device\n+ emulation support.\n+\n+ The library is an implementation of vfio-user protocol. It includes two main\n+ parts: client and server. Server implementation is for device provider to\n+ abstract its device. Client implementation is for device consumer to\n+ manipulate the emulated device.\n+\n+ See :doc:`../prog_guide/vfio_user_lib` for more information.\n \n Removed Items\n -------------\n", "prefixes": [ "v2", "9/9" ] }