From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 ; 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 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 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..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