[dpdk-dev] [PATCH v3 2/8] doc: add emudev library guide

[Chenbo Xia <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