From: Chenbo Xia <chenbo.xia@intel.com>
To: dev@dpdk.org, thomas@monjalon.net, david.marchand@redhat.com
Cc: stephen@networkplumber.org, cunming.liang@intel.com,
xiuchun.lu@intel.com, miao.li@intel.com, jingjing.wu@intel.com,
beilei.xing@intel.com
Subject: [dpdk-dev] [PATCH v3 2/8] doc: add emudev library guide
Date: Thu, 14 Jan 2021 14:25:06 +0800 [thread overview]
Message-ID: <20210114062512.45462-3-chenbo.xia@intel.com> (raw)
In-Reply-To: <20210114062512.45462-1-chenbo.xia@intel.com>
Add emudev library guide and update release notes.
Signed-off-by: Chenbo Xia <chenbo.xia@intel.com>
---
doc/guides/prog_guide/emudev.rst | 122 +++++++++++++++++++++++++
doc/guides/prog_guide/index.rst | 1 +
doc/guides/rel_notes/release_21_02.rst | 12 +++
3 files changed, 135 insertions(+)
create mode 100644 doc/guides/prog_guide/emudev.rst
diff --git a/doc/guides/prog_guide/emudev.rst b/doc/guides/prog_guide/emudev.rst
new file mode 100644
index 0000000000..e40213bb5e
--- /dev/null
+++ b/doc/guides/prog_guide/emudev.rst
@@ -0,0 +1,122 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2020 Intel Corporation.
+
+Emulated Device Library
+=================
+
+Introduction
+------------
+
+The DPDK Emudev library is an abstraction for emulated device. This library
+provides a generic set of APIs for device provider, data path provider and
+applications to use.
+
+A device provider could be implemented as a driver on vdev bus. It should
+expose itself as an emudev for applications to use. It is responsible for the
+device resource management and the device's internal logic. All specifics of a
+device, except data path handling, should be implemented in the device
+provider. The device provider uses emudev APIs mainly for create/destroy an
+emudev instance. The device provider should also use a transport to communicate
+with device consumer (e.g., virtual machine monitor or container). A potential
+choice could be vfio-user library, which implements the vfio-user protocol for
+emulating devices outside of a virtual machine monitor.
+
+A data path provider could be implemented as any type of driver on vdev bus.
+If the device you want to emulate is a network device, you could implement
+it as an ethdev driver. It is responsible for all data path handling. The data
+path provider uses emudev APIs mainly for getting device-related information
+from the device provider.
+
+Applications uses emudev APIs for device lifecycle management and configuration.
+
+Design
+------------
+
+Some key objects are designed in emudev.
+
+ ``Regions`` are the device layout exposed to the data path provider.
+
+ ``Queues`` are the data path queues that the data path provider needs. Queue
+ information includes queue base address, queue size, queue-related doorbell
+ and interrupt information.
+
+ ``Memory Table`` is the DMA mapping table. The data path provider could use
+ it to perform DMA read/write on device consumer's memory.
+
+Information of above key objects could be acquired through emudev APIs. The
+following will introduce the emudev APIs which are used by data path provider
+and applications. The APIs for device provider to use are allocate/release APIs
+and will not be listed because it's similar to other device abstraction.
+
+There are five categories of APIs:
+
+1. Lifecycle management
+
+* ``rte_emu_dev_start(dev_id)``
+* ``rte_emu_dev_stop(dev_id)``
+* ``rte_emu_dev_configure(dev_id)``
+* ``rte_emu_dev_close(dev_id)``
+
+ Above APIs are respectively for device start/stop/configure/close and mainly
+ for applications to use.
+
+ ``dev_id`` is the emudev device ID.
+
+2. Notification
+
+* ``rte_emu_subscribe_event(dev_id, ev_chnl)``
+* ``rte_emu_unsubscribe_event(dev_id, ev_chnl)``
+
+ Above APIs are for data path provider and applications to register events.
+ The mechanism of event notification could be different in different device
+ providers. A possbile implementation could be event callbacks.
+
+ ``ev_chnl`` is the event channel pointer. The definition varies between
+ different devices.
+
+3. Region-related
+
+* ``rte_emu_region_map(dev_id, index, region_size, base_addr)``
+* ``rte_emu_get_attr(dev_id, attr_name, attr)``
+* ``rte_emu_set_attr(dev_id, attr_name, attr)``
+
+ Above APIs are for data path provider and applications to read/write regions.
+ ``rte_emu_region_map`` is for directly mapping the region and use the mapped
+ address to read/write it. ``rte_emu_get_attr`` and ``rte_emu_set_attr`` are
+ respectively for getting/setting certain attributes in all regions.
+
+ Applications will set attributes or write regions for device configuration.
+
+ In ``rte_emu_region_map``:
+ - ``index`` is the region index.
+ - ``region_size`` is for saving the size of mapped region.
+ - ``base_addr`` is for saving the address of mapped region.
+
+ In ``rte_emu_get_attr`` and ``rte_emu_set_attr``:
+ - ``attr_name`` is the name of attribute. Note that attribute names are aligned
+ between device provider and data path provider for the same device.
+ - ``attr`` is the attribute value.
+
+4. Queue-related
+
+* ``rte_emu_get_queue_info(dev_id, queue, info)``
+* ``rte_emu_get_irq_info(dev_id, irq, info)``
+* ``rte_emu_get_db_info(dev_id, doorbell, info)``
+
+ Above APIs are for data path provider to get queue/interrupt/doorbell information.
+
+ - ``queue``, ``irq`` and ``doorbell`` are respectively the queue/interrupt/doorbell
+ index.
+ - ``info`` is for saving the queue/interrupt/doorbell info.
+
+5. Direct Memory Access
+
+* ``rte_emu_get_mem_table(dev_id, tb)``
+
+ Above APIs are for data path provider to get the information of DMA memory table.
+ The memory table implementation varies between different devices and memory table
+ operations should better be helper functions exposed by device provider. Because
+ address translation make a difference in data path performance, the memory table
+ implementation should have high efficiency.
+
+ ``tb`` is for saving the DMA memory table.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index f9847b1058..0ed15a0995 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -71,3 +71,4 @@ Programmer's Guide
profile_app
glossary
vfio_user_lib
+ emudev
diff --git a/doc/guides/rel_notes/release_21_02.rst b/doc/guides/rel_notes/release_21_02.rst
index eabbbfebef..9686930de3 100644
--- a/doc/guides/rel_notes/release_21_02.rst
+++ b/doc/guides/rel_notes/release_21_02.rst
@@ -67,6 +67,18 @@ New Features
See :doc:`../prog_guide/vfio_user_lib` for more information.
+* **Added emudev Library.**
+
+ Added an experimental library ``librte_emudev`` to provide device abstraction
+ for an emulated device.
+
+ The library abstracts an emulated device and provides several categories of
+ device-level APIs. The specific device type could be general (e.g, network,
+ crypto and etc.). It can be attached to another data path driver (e.g, ethdev
+ driver) to leverage the high performance of DPDK data path driver.
+
+ See :doc:`../prog_guide/emudev` for more information.
+
Removed Items
-------------
--
2.17.1
next prev parent reply other threads:[~2021-01-14 6:30 UTC|newest]
Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-12-18 7:47 [dpdk-dev] [PATCH 0/8] Introduce emudev library and iavf emudev driver Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 1/8] lib: introduce emudev library Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 2/8] doc: add emudev library guide Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 3/8] emu: introduce emulated iavf driver Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 4/8] emu/iavf: add vfio-user device register and unregister Chenbo Xia
2021-01-07 7:18 ` Xing, Beilei
2021-01-07 8:41 ` Xia, Chenbo
2020-12-18 7:47 ` [dpdk-dev] [PATCH 5/8] emu/iavf: add resource management and internal logic of iavf Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 6/8] emu/iavf: add emudev operations to fit in emudev framework Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 7/8] test/emudev: introduce functional test Chenbo Xia
2020-12-18 7:47 ` [dpdk-dev] [PATCH 8/8] doc: update release notes for iavf emudev driver Chenbo Xia
2020-12-18 9:53 ` [dpdk-dev] [PATCH 0/8] Introduce emudev library and " David Marchand
2020-12-19 6:11 ` Xia, Chenbo
2020-12-21 9:52 ` Maxime Coquelin
2020-12-21 12:01 ` Maxime Coquelin
2020-12-22 3:09 ` Xia, Chenbo
2020-12-22 8:48 ` Maxime Coquelin
2020-12-23 5:28 ` Xia, Chenbo
2020-12-19 6:27 ` [dpdk-dev] [PATCH v2 " Chenbo Xia
2020-12-19 6:27 ` [dpdk-dev] [PATCH v2 1/8] lib: introduce emudev library Chenbo Xia
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 2/8] doc: add emudev library guide Chenbo Xia
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 3/8] emu: introduce emulated iavf driver Chenbo Xia
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 4/8] emu/iavf: add vfio-user device register and unregister Chenbo Xia
2021-01-04 6:45 ` Wu, Jingjing
2021-01-05 1:26 ` Xia, Chenbo
2021-01-05 13:41 ` Wu, Jingjing
2021-01-06 7:41 ` Xia, Chenbo
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 5/8] emu/iavf: add resource management and internal logic of iavf Chenbo Xia
2020-12-29 6:05 ` Wu, Jingjing
2020-12-30 1:59 ` Xia, Chenbo
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 6/8] emu/iavf: add emudev operations to fit in emudev framework Chenbo Xia
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 7/8] test/emudev: introduce functional test Chenbo Xia
2020-12-19 6:28 ` [dpdk-dev] [PATCH v2 8/8] doc: update release notes for iavf emudev driver Chenbo Xia
2021-01-13 16:52 ` [dpdk-dev] [PATCH v2 0/8] Introduce emudev library and " Thomas Monjalon
2021-01-14 1:35 ` Xia, Chenbo
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 " Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 1/8] lib: introduce emudev library Chenbo Xia
2021-01-14 6:25 ` Chenbo Xia [this message]
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 3/8] emu: introduce emulated iavf driver Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 4/8] emu/iavf: add vfio-user device register and unregister Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 5/8] emu/iavf: add resource management and internal logic of iavf Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 6/8] emu/iavf: add emudev operations to fit in emudev framework Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 7/8] test/emudev: introduce functional test Chenbo Xia
2021-01-14 6:25 ` [dpdk-dev] [PATCH v3 8/8] doc: update release notes for iavf emudev driver Chenbo Xia
2024-02-12 22:49 ` [dpdk-dev] [PATCH v3 0/8] Introduce emudev library and " Stephen Hemminger
2023-06-14 19:47 ` [dpdk-dev] [PATCH " Stephen Hemminger
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210114062512.45462-3-chenbo.xia@intel.com \
--to=chenbo.xia@intel.com \
--cc=beilei.xing@intel.com \
--cc=cunming.liang@intel.com \
--cc=david.marchand@redhat.com \
--cc=dev@dpdk.org \
--cc=jingjing.wu@intel.com \
--cc=miao.li@intel.com \
--cc=stephen@networkplumber.org \
--cc=thomas@monjalon.net \
--cc=xiuchun.lu@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).