From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from dpdk.org (dpdk.org [92.243.14.124])
by inbox.dpdk.org (Postfix) with ESMTP id 7C912A04B5;
Sat, 19 Dec 2020 07:44:01 +0100 (CET)
Received: from [92.243.14.124] (localhost [127.0.0.1])
by dpdk.org (Postfix) with ESMTP id 429DBCB3A;
Sat, 19 Dec 2020 07:43:21 +0100 (CET)
Received: from mga18.intel.com (mga18.intel.com [134.134.136.126])
by dpdk.org (Postfix) with ESMTP id 92C6ACB12
for <dev@dpdk.org>; Sat, 19 Dec 2020 07:43:18 +0100 (CET)
IronPort-SDR: TR2u0f/Wy1b/5/sanuaQQM9qVbVCwpexsREi0PnSBjMNo8rmnjpN5Lq49ibt0/MbJFt1Nqbehi
SkygeObrhK2w==
X-IronPort-AV: E=McAfee;i="6000,8403,9839"; a="163285188"
X-IronPort-AV: E=Sophos;i="5.78,432,1599548400"; d="scan'208";a="163285188"
Received: from fmsmga001.fm.intel.com ([10.253.24.23])
by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
18 Dec 2020 22:43:18 -0800
IronPort-SDR: M+l78zg7O8LSfmi6CrAFZzq60xaEcind+xIPi9gHQl+1V0vWxaTQU38YFNpOAvLeKTnwQfkkMY
o5rQDZ4Nbr0w==
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.78,432,1599548400"; d="scan'208";a="454449603"
Received: from npg-dpdk-virtio-xiachenbo-nw.sh.intel.com ([10.67.119.123])
by fmsmga001.fm.intel.com with ESMTP; 18 Dec 2020 22:43:15 -0800
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
Date: Sat, 19 Dec 2020 14:28:00 +0800
Message-Id: <20201219062806.56477-3-chenbo.xia@intel.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20201219062806.56477-1-chenbo.xia@intel.com>
References: <20201218074736.93999-1-chenbo.xia@intel.com>
<20201219062806.56477-1-chenbo.xia@intel.com>
Subject: [dpdk-dev] [PATCH v2 2/8] doc: add emudev library guide
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<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>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>
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..91ad520de7
--- /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 tranport 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 6fbb6e8c39..3d26b6b580 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