Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/86510/?format=api
{ "id": 86510, "url": "http://patches.dpdk.org/api/patches/86510/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20210114062512.45462-3-chenbo.xia@intel.com/", "project": { "id": 1, "url": "http://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": "<20210114062512.45462-3-chenbo.xia@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20210114062512.45462-3-chenbo.xia@intel.com", "date": "2021-01-14T06:25:06", "name": "[v3,2/8] doc: add emudev library guide", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": true, "hash": "d10dd45b7ee512fe919d9ee226fe3281d5de7b11", "submitter": { "id": 1276, "url": "http://patches.dpdk.org/api/people/1276/?format=api", "name": "Chenbo Xia", "email": "chenbo.xia@intel.com" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20210114062512.45462-3-chenbo.xia@intel.com/mbox/", "series": [ { "id": 14712, "url": "http://patches.dpdk.org/api/series/14712/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=14712", "date": "2021-01-14T06:25:04", "name": "Introduce emudev library and iavf emudev driver", "version": 3, "mbox": "http://patches.dpdk.org/series/14712/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/86510/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/86510/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 E2CD2A0A02;\n\tThu, 14 Jan 2021 07:30:24 +0100 (CET)", "from [217.70.189.124] (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 9D193140E25;\n\tThu, 14 Jan 2021 07:30:15 +0100 (CET)", "from mga03.intel.com (mga03.intel.com [134.134.136.65])\n by mails.dpdk.org (Postfix) with ESMTP id E8E3F140E25\n for <dev@dpdk.org>; Thu, 14 Jan 2021 07:30:12 +0100 (CET)", "from fmsmga002.fm.intel.com ([10.253.24.26])\n by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 13 Jan 2021 22:30:12 -0800", "from npg-dpdk-virtio-xiachenbo-nw.sh.intel.com ([10.67.119.123])\n by fmsmga002.fm.intel.com with ESMTP; 13 Jan 2021 22:30:10 -0800" ], "IronPort-SDR": [ "\n x9LeGM7ZwCmVMLGkLALcC4EgXem4cwgP/HrSjMe139wol3ZX1vMIjILKFh7DeKmbEEHSMXtSC5\n w/nZAR8i/J/Q==", "\n sPgyrVPLoVC1eDNE3ANpcevANilMdCcLzkFn78gSb/8A4a8ibXQJtdS8hYwHN3V1uUoC4DKkL5\n HyVTOqTEfyRw==" ], "X-IronPort-AV": [ "E=McAfee;i=\"6000,8403,9863\"; a=\"178407161\"", "E=Sophos;i=\"5.79,346,1602572400\"; d=\"scan'208\";a=\"178407161\"", "E=Sophos;i=\"5.79,346,1602572400\"; d=\"scan'208\";a=\"400799411\"" ], "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:25:06 +0800", "Message-Id": "<20210114062512.45462-3-chenbo.xia@intel.com>", "X-Mailer": "git-send-email 2.17.1", "In-Reply-To": "<20210114062512.45462-1-chenbo.xia@intel.com>", "References": "<20201219062806.56477-1-chenbo.xia@intel.com>\n <20210114062512.45462-1-chenbo.xia@intel.com>", "Subject": "[dpdk-dev] [PATCH v3 2/8] doc: add emudev 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 emudev library guide and update release notes.\n\nSigned-off-by: Chenbo Xia <chenbo.xia@intel.com>\n---\n doc/guides/prog_guide/emudev.rst | 122 +++++++++++++++++++++++++\n doc/guides/prog_guide/index.rst | 1 +\n doc/guides/rel_notes/release_21_02.rst | 12 +++\n 3 files changed, 135 insertions(+)\n create mode 100644 doc/guides/prog_guide/emudev.rst", "diff": "diff --git a/doc/guides/prog_guide/emudev.rst b/doc/guides/prog_guide/emudev.rst\nnew file mode 100644\nindex 0000000000..e40213bb5e\n--- /dev/null\n+++ b/doc/guides/prog_guide/emudev.rst\n@@ -0,0 +1,122 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2020 Intel Corporation.\n+\n+Emulated Device Library\n+=================\n+\n+Introduction\n+------------\n+\n+The DPDK Emudev library is an abstraction for emulated device. This library\n+provides a generic set of APIs for device provider, data path provider and\n+applications to use.\n+\n+A device provider could be implemented as a driver on vdev bus. It should\n+expose itself as an emudev for applications to use. It is responsible for the\n+device resource management and the device's internal logic. All specifics of a\n+device, except data path handling, should be implemented in the device\n+provider. The device provider uses emudev APIs mainly for create/destroy an\n+emudev instance. The device provider should also use a transport to communicate\n+with device consumer (e.g., virtual machine monitor or container). A potential\n+choice could be vfio-user library, which implements the vfio-user protocol for\n+emulating devices outside of a virtual machine monitor.\n+\n+A data path provider could be implemented as any type of driver on vdev bus.\n+If the device you want to emulate is a network device, you could implement\n+it as an ethdev driver. It is responsible for all data path handling. The data\n+path provider uses emudev APIs mainly for getting device-related information\n+from the device provider.\n+\n+Applications uses emudev APIs for device lifecycle management and configuration.\n+\n+Design\n+------------\n+\n+Some key objects are designed in emudev.\n+\n+ ``Regions`` are the device layout exposed to the data path provider.\n+\n+ ``Queues`` are the data path queues that the data path provider needs. Queue\n+ information includes queue base address, queue size, queue-related doorbell\n+ and interrupt information.\n+\n+ ``Memory Table`` is the DMA mapping table. The data path provider could use\n+ it to perform DMA read/write on device consumer's memory.\n+\n+Information of above key objects could be acquired through emudev APIs. The\n+following will introduce the emudev APIs which are used by data path provider\n+and applications. The APIs for device provider to use are allocate/release APIs\n+and will not be listed because it's similar to other device abstraction.\n+\n+There are five categories of APIs:\n+\n+1. Lifecycle management\n+\n+* ``rte_emu_dev_start(dev_id)``\n+* ``rte_emu_dev_stop(dev_id)``\n+* ``rte_emu_dev_configure(dev_id)``\n+* ``rte_emu_dev_close(dev_id)``\n+\n+ Above APIs are respectively for device start/stop/configure/close and mainly\n+ for applications to use.\n+\n+ ``dev_id`` is the emudev device ID.\n+\n+2. Notification\n+\n+* ``rte_emu_subscribe_event(dev_id, ev_chnl)``\n+* ``rte_emu_unsubscribe_event(dev_id, ev_chnl)``\n+\n+ Above APIs are for data path provider and applications to register events.\n+ The mechanism of event notification could be different in different device\n+ providers. A possbile implementation could be event callbacks.\n+\n+ ``ev_chnl`` is the event channel pointer. The definition varies between\n+ different devices.\n+\n+3. Region-related\n+\n+* ``rte_emu_region_map(dev_id, index, region_size, base_addr)``\n+* ``rte_emu_get_attr(dev_id, attr_name, attr)``\n+* ``rte_emu_set_attr(dev_id, attr_name, attr)``\n+\n+ Above APIs are for data path provider and applications to read/write regions.\n+ ``rte_emu_region_map`` is for directly mapping the region and use the mapped\n+ address to read/write it. ``rte_emu_get_attr`` and ``rte_emu_set_attr`` are\n+ respectively for getting/setting certain attributes in all regions.\n+\n+ Applications will set attributes or write regions for device configuration.\n+\n+ In ``rte_emu_region_map``:\n+ - ``index`` is the region index.\n+ - ``region_size`` is for saving the size of mapped region.\n+ - ``base_addr`` is for saving the address of mapped region.\n+\n+ In ``rte_emu_get_attr`` and ``rte_emu_set_attr``:\n+ - ``attr_name`` is the name of attribute. Note that attribute names are aligned\n+ between device provider and data path provider for the same device.\n+ - ``attr`` is the attribute value.\n+\n+4. Queue-related\n+\n+* ``rte_emu_get_queue_info(dev_id, queue, info)``\n+* ``rte_emu_get_irq_info(dev_id, irq, info)``\n+* ``rte_emu_get_db_info(dev_id, doorbell, info)``\n+\n+ Above APIs are for data path provider to get queue/interrupt/doorbell information.\n+\n+ - ``queue``, ``irq`` and ``doorbell`` are respectively the queue/interrupt/doorbell\n+ index.\n+ - ``info`` is for saving the queue/interrupt/doorbell info.\n+\n+5. Direct Memory Access\n+\n+* ``rte_emu_get_mem_table(dev_id, tb)``\n+\n+ Above APIs are for data path provider to get the information of DMA memory table.\n+ The memory table implementation varies between different devices and memory table\n+ operations should better be helper functions exposed by device provider. Because\n+ address translation make a difference in data path performance, the memory table\n+ implementation should have high efficiency.\n+\n+ ``tb`` is for saving the DMA memory table.\ndiff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst\nindex f9847b1058..0ed15a0995 100644\n--- a/doc/guides/prog_guide/index.rst\n+++ b/doc/guides/prog_guide/index.rst\n@@ -71,3 +71,4 @@ Programmer's Guide\n profile_app\n glossary\n vfio_user_lib\n+ emudev\ndiff --git a/doc/guides/rel_notes/release_21_02.rst b/doc/guides/rel_notes/release_21_02.rst\nindex eabbbfebef..9686930de3 100644\n--- a/doc/guides/rel_notes/release_21_02.rst\n+++ b/doc/guides/rel_notes/release_21_02.rst\n@@ -67,6 +67,18 @@ New Features\n \n See :doc:`../prog_guide/vfio_user_lib` for more information.\n \n+* **Added emudev Library.**\n+\n+ Added an experimental library ``librte_emudev`` to provide device abstraction\n+ for an emulated device.\n+\n+ The library abstracts an emulated device and provides several categories of\n+ device-level APIs. The specific device type could be general (e.g, network,\n+ crypto and etc.). It can be attached to another data path driver (e.g, ethdev\n+ driver) to leverage the high performance of DPDK data path driver.\n+\n+ See :doc:`../prog_guide/emudev` for more information.\n+\n Removed Items\n -------------\n \n", "prefixes": [ "v3", "2/8" ] }