DPDK patches and discussions
 help / color / mirror / Atom feed
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


  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).