Add emudev library guide and update release notes.
Signed-off-by: Chenbo Xia <chenbo....@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
