From patchwork Thu Jan 14 06:25:06 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Chenbo Xia X-Patchwork-Id: 86510 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E2CD2A0A02; Thu, 14 Jan 2021 07:30:24 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 9D193140E25; Thu, 14 Jan 2021 07:30:15 +0100 (CET) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id E8E3F140E25 for ; Thu, 14 Jan 2021 07:30:12 +0100 (CET) IronPort-SDR: x9LeGM7ZwCmVMLGkLALcC4EgXem4cwgP/HrSjMe139wol3ZX1vMIjILKFh7DeKmbEEHSMXtSC5 w/nZAR8i/J/Q== X-IronPort-AV: E=McAfee;i="6000,8403,9863"; a="178407161" X-IronPort-AV: E=Sophos;i="5.79,346,1602572400"; d="scan'208";a="178407161" Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 Jan 2021 22:30:12 -0800 IronPort-SDR: sPgyrVPLoVC1eDNE3ANpcevANilMdCcLzkFn78gSb/8A4a8ibXQJtdS8hYwHN3V1uUoC4DKkL5 HyVTOqTEfyRw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.79,346,1602572400"; d="scan'208";a="400799411" Received: from npg-dpdk-virtio-xiachenbo-nw.sh.intel.com ([10.67.119.123]) by fmsmga002.fm.intel.com with ESMTP; 13 Jan 2021 22:30:10 -0800 From: Chenbo Xia 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 Date: Thu, 14 Jan 2021 14:25:06 +0800 Message-Id: <20210114062512.45462-3-chenbo.xia@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210114062512.45462-1-chenbo.xia@intel.com> References: <20201219062806.56477-1-chenbo.xia@intel.com> <20210114062512.45462-1-chenbo.xia@intel.com> Subject: [dpdk-dev] [PATCH v3 2/8] doc: add emudev library guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add emudev library guide and update release notes. Signed-off-by: Chenbo Xia --- 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 -------------