Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/96610/?format=api
{ "id": 96610, "url": "http://patchwork.dpdk.org/api/patches/96610/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/patch/1627990189-36531-2-git-send-email-fengchengwen@huawei.com/", "project": { "id": 1, "url": "http://patchwork.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1627990189-36531-2-git-send-email-fengchengwen@huawei.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1627990189-36531-2-git-send-email-fengchengwen@huawei.com", "date": "2021-08-03T11:29:44", "name": "[v13,1/6] dmadev: introduce DMA device library public APIs", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "fb750b8680a5fac3c7dda8d492d3a742d128fb1d", "submitter": { "id": 2146, "url": "http://patchwork.dpdk.org/api/people/2146/?format=api", "name": "fengchengwen", "email": "fengchengwen@huawei.com" }, "delegate": { "id": 1, "url": "http://patchwork.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patchwork.dpdk.org/project/dpdk/patch/1627990189-36531-2-git-send-email-fengchengwen@huawei.com/mbox/", "series": [ { "id": 18161, "url": "http://patchwork.dpdk.org/api/series/18161/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/list/?series=18161", "date": "2021-08-03T11:29:47", "name": "support dmadev", "version": 13, "mbox": "http://patchwork.dpdk.org/series/18161/mbox/" } ], "comments": "http://patchwork.dpdk.org/api/patches/96610/comments/", "check": "success", "checks": "http://patchwork.dpdk.org/api/patches/96610/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "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])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 8A757A0A0C;\n\tTue, 3 Aug 2021 13:34:05 +0200 (CEST)", "from [217.70.189.124] (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id D2950411DF;\n\tTue, 3 Aug 2021 13:33:42 +0200 (CEST)", "from szxga03-in.huawei.com (szxga03-in.huawei.com [45.249.212.189])\n by mails.dpdk.org (Postfix) with ESMTP id EF6D5411BE\n for <dev@dpdk.org>; Tue, 3 Aug 2021 13:33:36 +0200 (CEST)", "from dggemv703-chm.china.huawei.com (unknown [172.30.72.56])\n by szxga03-in.huawei.com (SkyGuard) with ESMTP id 4GfCLN2Q1Xz82HF;\n Tue, 3 Aug 2021 19:28:44 +0800 (CST)", "from dggpeml500024.china.huawei.com (7.185.36.10) by\n dggemv703-chm.china.huawei.com (10.3.19.46) with Microsoft SMTP Server\n (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id\n 15.1.2176.2; Tue, 3 Aug 2021 19:33:34 +0800", "from localhost.localdomain (10.67.165.24) by\n dggpeml500024.china.huawei.com (7.185.36.10) with Microsoft SMTP Server\n (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id\n 15.1.2176.2; Tue, 3 Aug 2021 19:33:34 +0800" ], "From": "Chengwen Feng <fengchengwen@huawei.com>", "To": "<thomas@monjalon.net>, <ferruh.yigit@intel.com>,\n <bruce.richardson@intel.com>, <jerinj@marvell.com>, <jerinjacobk@gmail.com>,\n <andrew.rybchenko@oktetlabs.ru>", "CC": "<dev@dpdk.org>, <mb@smartsharesystems.com>, <nipun.gupta@nxp.com>,\n <hemant.agrawal@nxp.com>, <maxime.coquelin@redhat.com>,\n <honnappa.nagarahalli@arm.com>, <david.marchand@redhat.com>,\n <sburla@marvell.com>, <pkapoor@marvell.com>, <konstantin.ananyev@intel.com>", "Date": "Tue, 3 Aug 2021 19:29:44 +0800", "Message-ID": "<1627990189-36531-2-git-send-email-fengchengwen@huawei.com>", "X-Mailer": "git-send-email 2.8.1", "In-Reply-To": "<1627990189-36531-1-git-send-email-fengchengwen@huawei.com>", "References": "<1625231891-2963-1-git-send-email-fengchengwen@huawei.com>\n <1627990189-36531-1-git-send-email-fengchengwen@huawei.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=\"UTF-8\"", "Content-Transfer-Encoding": "8bit", "X-Originating-IP": "[10.67.165.24]", "X-ClientProxiedBy": "dggems702-chm.china.huawei.com (10.3.19.179) To\n dggpeml500024.china.huawei.com (7.185.36.10)", "X-CFilter-Loop": "Reflected", "Subject": "[dpdk-dev] [PATCH v13 1/6] dmadev: introduce DMA device library\n public APIs", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <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>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "The 'dmadevice' is a generic type of DMA device.\n\nThis patch introduce the 'dmadevice' public APIs which expose generic\noperations that can enable configuration and I/O with the DMA devices.\n\nSigned-off-by: Chengwen Feng <fengchengwen@huawei.com>\nAcked-by: Bruce Richardson <bruce.richardson@intel.com>\nAcked-by: Morten Brørup <mb@smartsharesystems.com>\nAcked-by: Jerin Jacob <jerinjacobk@gmail.com>\n---\n doc/api/doxy-api-index.md | 1 +\n doc/api/doxy-api.conf.in | 1 +\n lib/dmadev/meson.build | 4 +\n lib/dmadev/rte_dmadev.h | 962 ++++++++++++++++++++++++++++++++++++++++++++++\n lib/dmadev/version.map | 25 ++\n lib/meson.build | 1 +\n 6 files changed, 994 insertions(+)\n create mode 100644 lib/dmadev/meson.build\n create mode 100644 lib/dmadev/rte_dmadev.h\n create mode 100644 lib/dmadev/version.map", "diff": "diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md\nindex 1992107..ce08250 100644\n--- a/doc/api/doxy-api-index.md\n+++ b/doc/api/doxy-api-index.md\n@@ -27,6 +27,7 @@ The public API headers are grouped by topics:\n [event_timer_adapter] (@ref rte_event_timer_adapter.h),\n [event_crypto_adapter] (@ref rte_event_crypto_adapter.h),\n [rawdev] (@ref rte_rawdev.h),\n+ [dmadev] (@ref rte_dmadev.h),\n [metrics] (@ref rte_metrics.h),\n [bitrate] (@ref rte_bitrate.h),\n [latency] (@ref rte_latencystats.h),\ndiff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in\nindex 325a019..a44a92b 100644\n--- a/doc/api/doxy-api.conf.in\n+++ b/doc/api/doxy-api.conf.in\n@@ -34,6 +34,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \\\n @TOPDIR@/lib/cmdline \\\n @TOPDIR@/lib/compressdev \\\n @TOPDIR@/lib/cryptodev \\\n+ @TOPDIR@/lib/dmadev \\\n @TOPDIR@/lib/distributor \\\n @TOPDIR@/lib/efd \\\n @TOPDIR@/lib/ethdev \\\ndiff --git a/lib/dmadev/meson.build b/lib/dmadev/meson.build\nnew file mode 100644\nindex 0000000..6d5bd85\n--- /dev/null\n+++ b/lib/dmadev/meson.build\n@@ -0,0 +1,4 @@\n+# SPDX-License-Identifier: BSD-3-Clause\n+# Copyright(c) 2021 HiSilicon Limited.\n+\n+headers = files('rte_dmadev.h')\ndiff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h\nnew file mode 100644\nindex 0000000..1090b06\n--- /dev/null\n+++ b/lib/dmadev/rte_dmadev.h\n@@ -0,0 +1,962 @@\n+/* SPDX-License-Identifier: BSD-3-Clause\n+ * Copyright(c) 2021 HiSilicon Limited.\n+ * Copyright(c) 2021 Intel Corporation.\n+ * Copyright(c) 2021 Marvell International Ltd.\n+ * Copyright(c) 2021 SmartShare Systems.\n+ */\n+\n+#ifndef _RTE_DMADEV_H_\n+#define _RTE_DMADEV_H_\n+\n+/**\n+ * @file rte_dmadev.h\n+ *\n+ * RTE DMA (Direct Memory Access) device APIs.\n+ *\n+ * The DMA framework is built on the following model:\n+ *\n+ * --------------- --------------- ---------------\n+ * | virtual DMA | | virtual DMA | | virtual DMA |\n+ * | channel | | channel | | channel |\n+ * --------------- --------------- ---------------\n+ * | | |\n+ * ------------------ |\n+ * | |\n+ * ------------ ------------\n+ * | dmadev | | dmadev |\n+ * ------------ ------------\n+ * | |\n+ * ------------------ ------------------\n+ * | HW-DMA-channel | | HW-DMA-channel |\n+ * ------------------ ------------------\n+ * | |\n+ * --------------------------------\n+ * |\n+ * ---------------------\n+ * | HW-DMA-Controller |\n+ * ---------------------\n+ *\n+ * The DMA controller could have multiple HW-DMA-channels (aka. HW-DMA-queues),\n+ * each HW-DMA-channel should be represented by a dmadev.\n+ *\n+ * The dmadev could create multiple virtual DMA channels, each virtual DMA\n+ * channel represents a different transfer context. The DMA operation request\n+ * must be submitted to the virtual DMA channel. e.g. Application could create\n+ * virtual DMA channel 0 for memory-to-memory transfer scenario, and create\n+ * virtual DMA channel 1 for memory-to-device transfer scenario.\n+ *\n+ * The dmadev are dynamically allocated by rte_dmadev_pmd_allocate() during the\n+ * PCI/SoC device probing phase performed at EAL initialization time. And could\n+ * be released by rte_dmadev_pmd_release() during the PCI/SoC device removing\n+ * phase.\n+ *\n+ * This framework uses 'uint16_t dev_id' as the device identifier of a dmadev,\n+ * and 'uint16_t vchan' as the virtual DMA channel identifier in one dmadev.\n+ *\n+ * The functions exported by the dmadev API to setup a device designated by its\n+ * device identifier must be invoked in the following order:\n+ * - rte_dmadev_configure()\n+ * - rte_dmadev_vchan_setup()\n+ * - rte_dmadev_start()\n+ *\n+ * Then, the application can invoke dataplane APIs to process jobs.\n+ *\n+ * If the application wants to change the configuration (i.e. invoke\n+ * rte_dmadev_configure() or rte_dmadev_vchan_setup()), it must invoke\n+ * rte_dmadev_stop() first to stop the device and then do the reconfiguration\n+ * before invoking rte_dmadev_start() again. The dataplane APIs should not be\n+ * invoked when the device is stopped.\n+ *\n+ * Finally, an application can close a dmadev by invoking the\n+ * rte_dmadev_close() function.\n+ *\n+ * The dataplane APIs include two parts:\n+ * The first part is the submission of operation requests:\n+ * - rte_dmadev_copy()\n+ * - rte_dmadev_copy_sg()\n+ * - rte_dmadev_fill()\n+ * - rte_dmadev_submit()\n+ *\n+ * These APIs could work with different virtual DMA channels which have\n+ * different contexts.\n+ *\n+ * The first three APIs are used to submit the operation request to the virtual\n+ * DMA channel, if the submission is successful, an uint16_t ring_idx is\n+ * returned, otherwise a negative number is returned.\n+ *\n+ * The last API was used to issue doorbell to hardware, and also there are flags\n+ * (@see RTE_DMA_OP_FLAG_SUBMIT) parameter of the first three APIs could do the\n+ * same work.\n+ *\n+ * The second part is to obtain the result of requests:\n+ * - rte_dmadev_completed()\n+ * - return the number of operation requests completed successfully.\n+ * - rte_dmadev_completed_status()\n+ * - return the number of operation requests completed.\n+ *\n+ * @note If the dmadev works in silent mode (@see RTE_DMADEV_CAPA_SILENT),\n+ * application does not invoke the above two completed APIs.\n+ *\n+ * About the ring_idx which enqueue APIs (e.g. rte_dmadev_copy()\n+ * rte_dmadev_fill()) returned, the rules are as follows:\n+ * - ring_idx for each virtual DMA channel are independent.\n+ * - For a virtual DMA channel, the ring_idx is monotonically incremented,\n+ * when it reach UINT16_MAX, it wraps back to zero.\n+ * - This ring_idx can be used by applications to track per-operation\n+ * metadata in an application-defined circular ring.\n+ * - The initial ring_idx of a virtual DMA channel is zero, after the\n+ * device is stopped, the ring_idx needs to be reset to zero.\n+ *\n+ * One example:\n+ * - step-1: start one dmadev\n+ * - step-2: enqueue a copy operation, the ring_idx return is 0\n+ * - step-3: enqueue a copy operation again, the ring_idx return is 1\n+ * - ...\n+ * - step-101: stop the dmadev\n+ * - step-102: start the dmadev\n+ * - step-103: enqueue a copy operation, the cookie return is 0\n+ * - ...\n+ * - step-x+0: enqueue a fill operation, the ring_idx return is 65535\n+ * - step-x+1: enqueue a copy operation, the ring_idx return is 0\n+ * - ...\n+ *\n+ * The DMA operation address used in enqueue APIs (i.e. rte_dmadev_copy(),\n+ * rte_dmadev_copy_sg(), rte_dmadev_fill()) defined as rte_iova_t type. The\n+ * dmadev supports two types of address: memory address and device address.\n+ *\n+ * - memory address: the source and destination address of the memory-to-memory\n+ * transfer type, or the source address of the memory-to-device transfer type,\n+ * or the destination address of the device-to-memory transfer type.\n+ * @note If the device support SVA (@see RTE_DMADEV_CAPA_SVA), the memory\n+ * address can be any VA address, otherwise it must be an IOVA address.\n+ *\n+ * - device address: the source and destination address of the device-to-device\n+ * transfer type, or the source address of the device-to-memory transfer type,\n+ * or the destination address of the memory-to-device transfer type.\n+ *\n+ * By default, all the functions of the dmadev API exported by a PMD are\n+ * lock-free functions which assume to not be invoked in parallel on different\n+ * logical cores to work on the same target dmadev object.\n+ * @note Different virtual DMA channels on the same dmadev *DO NOT* support\n+ * parallel invocation because these virtual DMA channels share the same\n+ * HW-DMA-channel.\n+ *\n+ */\n+\n+#include <rte_common.h>\n+#include <rte_compat.h>\n+#include <rte_dev.h>\n+#include <rte_errno.h>\n+#include <rte_memory.h>\n+\n+#ifdef __cplusplus\n+extern \"C\" {\n+#endif\n+\n+#define RTE_DMADEV_NAME_MAX_LEN\tRTE_DEV_NAME_MAX_LEN\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Get the device identifier for the named DMA device.\n+ *\n+ * @param name\n+ * DMA device name.\n+ *\n+ * @return\n+ * Returns DMA device identifier on success.\n+ * - <0: Failure to find named DMA device.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_get_dev_id(const char *name);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * @param dev_id\n+ * DMA device index.\n+ *\n+ * @return\n+ * - If the device index is valid (true) or not (false).\n+ */\n+__rte_experimental\n+bool\n+rte_dmadev_is_valid_dev(uint16_t dev_id);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Get the total number of DMA devices that have been successfully\n+ * initialised.\n+ *\n+ * @return\n+ * The total number of usable DMA devices.\n+ */\n+__rte_experimental\n+uint16_t\n+rte_dmadev_count(void);\n+\n+/* Enumerates DMA device capabilities. */\n+#define RTE_DMADEV_CAPA_MEM_TO_MEM\t(1ull << 0)\n+/**< DMA device support memory-to-memory transfer.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ */\n+\n+#define RTE_DMADEV_CAPA_MEM_TO_DEV\t(1ull << 1)\n+/**< DMA device support memory-to-device transfer.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ * @see struct rte_dmadev_port_param::port_type\n+ */\n+\n+#define RTE_DMADEV_CAPA_DEV_TO_MEM\t(1ull << 2)\n+/**< DMA device support device-to-memory transfer.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ * @see struct rte_dmadev_port_param::port_type\n+ */\n+\n+#define RTE_DMADEV_CAPA_DEV_TO_DEV\t(1ull << 3)\n+/**< DMA device support device-to-device transfer.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ * @see struct rte_dmadev_port_param::port_type\n+ */\n+\n+#define RTE_DMADEV_CAPA_SVA\t\t(1ull << 4)\n+/**< DMA device support SVA which could use VA as DMA address.\n+ * If device support SVA then application could pass any VA address like memory\n+ * from rte_malloc(), rte_memzone(), malloc, stack memory.\n+ * If device don't support SVA, then application should pass IOVA address which\n+ * from rte_malloc(), rte_memzone().\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ */\n+\n+#define RTE_DMADEV_CAPA_SILENT\t\t(1ull << 5)\n+/**< DMA device support work in silent mode.\n+ * In this mode, application don't required to invoke rte_dmadev_completed*()\n+ * API.\n+ *\n+ * @see struct rte_dmadev_conf::silent_mode\n+ */\n+\n+#define RTE_DMADEV_CAPA_OPS_COPY\t(1ull << 32)\n+/**< DMA device support copy ops.\n+ * This capability start with index of 32, so that it could leave gap between\n+ * normal capability and ops capability.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ */\n+\n+#define RTE_DMADEV_CAPA_OPS_COPY_SG\t(1ull << 33)\n+/**< DMA device support scatter-gather list copy ops.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ */\n+\n+#define RTE_DMADEV_CAPA_OPS_FILL\t(1ull << 34)\n+/**< DMA device support fill ops.\n+ *\n+ * @see struct rte_dmadev_info::dev_capa\n+ */\n+\n+/**\n+ * A structure used to retrieve the information of a DMA device.\n+ */\n+struct rte_dmadev_info {\n+\tstruct rte_device *device; /**< Generic Device information. */\n+\tuint64_t dev_capa; /**< Device capabilities (RTE_DMADEV_CAPA_*). */\n+\tuint16_t max_vchans;\n+\t/**< Maximum number of virtual DMA channels supported. */\n+\tuint16_t max_desc;\n+\t/**< Maximum allowed number of virtual DMA channel descriptors. */\n+\tuint16_t min_desc;\n+\t/**< Minimum allowed number of virtual DMA channel descriptors. */\n+\tuint16_t max_sges;\n+\t/**< Maximum number of source or destination scatter-gather entry\n+\t * supported.\n+\t * If the device does not support COPY_SG capability, this value can be\n+\t * zero.\n+\t * If the device supports COPY_SG capability, then rte_dmadev_copy_sg()\n+\t * parameter nb_src/nb_dst should not exceed this value.\n+\t */\n+\tuint16_t nb_vchans; /**< Number of virtual DMA channel configured. */\n+};\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Retrieve information of a DMA device.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param[out] dev_info\n+ * A pointer to a structure of type *rte_dmadev_info* to be filled with the\n+ * information of the device.\n+ *\n+ * @return\n+ * - =0: Success, driver updates the information of the DMA device.\n+ * - <0: Error code returned by the driver info get function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_info_get(uint16_t dev_id, struct rte_dmadev_info *dev_info);\n+\n+/**\n+ * A structure used to configure a DMA device.\n+ */\n+struct rte_dmadev_conf {\n+\tuint16_t max_vchans;\n+\t/**< Maximum number of virtual DMA channel to use.\n+\t * This value cannot be greater than the field 'max_vchans' of struct\n+\t * rte_dmadev_info which get from rte_dmadev_info_get().\n+\t */\n+\tbool enable_silent;\n+\t/**< Indicates whether to enable silent mode.\n+\t * false-default mode, true-silent mode.\n+\t * This value can be set to true only when the SILENT capability is\n+\t * supported.\n+\t *\n+\t * @see RTE_DMADEV_CAPA_SILENT\n+\t */\n+};\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Configure a DMA device.\n+ *\n+ * This function must be invoked first before any other function in the\n+ * API. This function can also be re-invoked when a device is in the\n+ * stopped state.\n+ *\n+ * @param dev_id\n+ * The identifier of the device to configure.\n+ * @param dev_conf\n+ * The DMA device configuration structure encapsulated into rte_dmadev_conf\n+ * object.\n+ *\n+ * @return\n+ * - =0: Success, device configured.\n+ * - <0: Error code returned by the driver configuration function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_configure(uint16_t dev_id, const struct rte_dmadev_conf *dev_conf);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Start a DMA device.\n+ *\n+ * The device start step is the last one and consists of setting the DMA\n+ * to start accepting jobs.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ *\n+ * @return\n+ * - =0: Success, device started.\n+ * - <0: Error code returned by the driver start function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_start(uint16_t dev_id);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Stop a DMA device.\n+ *\n+ * The device can be restarted with a call to rte_dmadev_start().\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ *\n+ * @return\n+ * - =0: Success, device stopped.\n+ * - <0: Error code returned by the driver stop function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_stop(uint16_t dev_id);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Close a DMA device.\n+ *\n+ * The device cannot be restarted after this call.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ *\n+ * @return\n+ * - =0: Successfully close device\n+ * - <0: Failure to close device\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_close(uint16_t dev_id);\n+\n+/**\n+ * rte_dma_direction - DMA transfer direction defines.\n+ */\n+enum rte_dma_direction {\n+\tRTE_DMA_DIR_MEM_TO_MEM,\n+\t/**< DMA transfer direction - from memory to memory.\n+\t *\n+\t * @see struct rte_dmadev_vchan_conf::direction\n+\t */\n+\tRTE_DMA_DIR_MEM_TO_DEV,\n+\t/**< DMA transfer direction - from memory to device.\n+\t * In a typical scenario, the SoCs are installed on host servers as\n+\t * iNICs through the PCIe interface. In this case, the SoCs works in\n+\t * EP(endpoint) mode, it could initiate a DMA move request from memory\n+\t * (which is SoCs memory) to device (which is host memory).\n+\t *\n+\t * @see struct rte_dmadev_vchan_conf::direction\n+\t */\n+\tRTE_DMA_DIR_DEV_TO_MEM,\n+\t/**< DMA transfer direction - from device to memory.\n+\t * In a typical scenario, the SoCs are installed on host servers as\n+\t * iNICs through the PCIe interface. In this case, the SoCs works in\n+\t * EP(endpoint) mode, it could initiate a DMA move request from device\n+\t * (which is host memory) to memory (which is SoCs memory).\n+\t *\n+\t * @see struct rte_dmadev_vchan_conf::direction\n+\t */\n+\tRTE_DMA_DIR_DEV_TO_DEV,\n+\t/**< DMA transfer direction - from device to device.\n+\t * In a typical scenario, the SoCs are installed on host servers as\n+\t * iNICs through the PCIe interface. In this case, the SoCs works in\n+\t * EP(endpoint) mode, it could initiate a DMA move request from device\n+\t * (which is host memory) to the device (which is another host memory).\n+\t *\n+\t * @see struct rte_dmadev_vchan_conf::direction\n+\t */\n+};\n+\n+/**\n+ * enum rte_dmadev_port_type - DMA access port type defines.\n+ *\n+ * @see struct rte_dmadev_port_param::port_type\n+ */\n+enum rte_dmadev_port_type {\n+\tRTE_DMADEV_PORT_NONE,\n+\tRTE_DMADEV_PORT_PCIE, /**< The DMA access port is PCIe. */\n+};\n+\n+/**\n+ * A structure used to descript DMA access port parameters.\n+ *\n+ * @see struct rte_dmadev_vchan_conf::src_port\n+ * @see struct rte_dmadev_vchan_conf::dst_port\n+ */\n+struct rte_dmadev_port_param {\n+\tenum rte_dmadev_port_type port_type;\n+\t/**< The device access port type.\n+\t * @see enum rte_dmadev_port_type\n+\t */\n+\tunion {\n+\t\t/** PCIe access port parameters.\n+\t\t *\n+\t\t * The following model shows SoC's PCIe module connects to\n+\t\t * multiple PCIe hosts and multiple endpoints. The PCIe module\n+\t\t * has an integrated DMA controller.\n+\t\t *\n+\t\t * If the DMA wants to access the memory of host A, it can be\n+\t\t * initiated by PF1 in core0, or by VF0 of PF0 in core0.\n+\t\t *\n+\t\t * \\code{.unparsed}\n+\t\t * System Bus\n+\t\t * | ----------PCIe module----------\n+\t\t * | Bus\n+\t\t * | Interface\n+\t\t * | ----- ------------------\n+\t\t * | | | | PCIe Core0 |\n+\t\t * | | | | | -----------\n+\t\t * | | | | PF-0 -- VF-0 | | Host A |\n+\t\t * | | |--------| |- VF-1 |--------| Root |\n+\t\t * | | | | PF-1 | | Complex |\n+\t\t * | | | | PF-2 | -----------\n+\t\t * | | | ------------------\n+\t\t * | | |\n+\t\t * | | | ------------------\n+\t\t * | | | | PCIe Core1 |\n+\t\t * | | | | | -----------\n+\t\t * | | | | PF-0 -- VF-0 | | Host B |\n+\t\t * |-----| |--------| PF-1 -- VF-0 |--------| Root |\n+\t\t * | | | | |- VF-1 | | Complex |\n+\t\t * | | | | PF-2 | -----------\n+\t\t * | | | ------------------\n+\t\t * | | |\n+\t\t * | | | ------------------\n+\t\t * | |DMA| | | ------\n+\t\t * | | | | |--------| EP |\n+\t\t * | | |--------| PCIe Core2 | ------\n+\t\t * | | | | | ------\n+\t\t * | | | | |--------| EP |\n+\t\t * | | | | | ------\n+\t\t * | ----- ------------------\n+\t\t *\n+\t\t * \\endcode\n+\t\t *\n+\t\t * @note If some fields can not be supported by the\n+\t\t * hardware/driver, then the driver ignores those fields.\n+\t\t * Please check driver-specific documentation for limitations\n+\t\t * and capablites.\n+\t\t */\n+\t\tstruct {\n+\t\t\tuint64_t coreid : 4; /**< PCIe core id used. */\n+\t\t\tuint64_t pfid : 8; /**< PF id used. */\n+\t\t\tuint64_t vfen : 1; /**< VF enable bit. */\n+\t\t\tuint64_t vfid : 16; /**< VF id used. */\n+\t\t\tuint64_t pasid : 20;\n+\t\t\t/**< The pasid filed in TLP packet. */\n+\t\t\tuint64_t attr : 3;\n+\t\t\t/**< The attributes filed in TLP packet. */\n+\t\t\tuint64_t ph : 2;\n+\t\t\t/**< The processing hint filed in TLP packet. */\n+\t\t\tuint64_t st : 16;\n+\t\t\t/**< The steering tag filed in TLP packet. */\n+\t\t} pcie;\n+\t};\n+\tuint64_t reserved[2]; /**< Reserved for future fields. */\n+};\n+\n+/**\n+ * A structure used to configure a virtual DMA channel.\n+ */\n+struct rte_dmadev_vchan_conf {\n+\tenum rte_dma_direction direction;\n+\t/**< Transfer direction\n+\t * @see enum rte_dma_direction\n+\t */\n+\tuint16_t nb_desc;\n+\t/**< Number of descriptor for the virtual DMA channel */\n+\tstruct rte_dmadev_port_param src_port;\n+\t/**< 1) Used to describes the device access port parameter in the\n+\t * device-to-memory transfer scenario.\n+\t * 2) Used to describes the source device access port parameter in the\n+\t * device-to-device transfer scenario.\n+\t * @see struct rte_dmadev_port_param\n+\t */\n+\tstruct rte_dmadev_port_param dst_port;\n+\t/**< 1) Used to describes the device access port parameter in the\n+\t * memory-to-device transfer scenario.\n+\t * 2) Used to describes the destination device access port parameter in\n+\t * the device-to-device transfer scenario.\n+\t * @see struct rte_dmadev_port_param\n+\t */\n+};\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Allocate and set up a virtual DMA channel.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param conf\n+ * The virtual DMA channel configuration structure encapsulated into\n+ * rte_dmadev_vchan_conf object.\n+ *\n+ * @return\n+ * - >=0: Allocate success, it is the virtual DMA channel id. This value must\n+ * be less than the field 'max_vchans' of struct rte_dmadev_conf\n+ * which configured by rte_dmadev_configure().\n+ * - <0: Error code returned by the driver virtual channel setup function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_vchan_setup(uint16_t dev_id,\n+\t\t const struct rte_dmadev_vchan_conf *conf);\n+\n+/**\n+ * rte_dmadev_stats - running statistics.\n+ */\n+struct rte_dmadev_stats {\n+\tuint64_t submitted_count;\n+\t/**< Count of operations which were submitted to hardware. */\n+\tuint64_t completed_fail_count;\n+\t/**< Count of operations which failed to complete. */\n+\tuint64_t completed_count;\n+\t/**< Count of operations which successfully complete. */\n+};\n+\n+#define RTE_DMADEV_ALL_VCHAN\t0xFFFFu\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Retrieve basic statistics of a or all virtual DMA channel(s).\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * If equal RTE_DMADEV_ALL_VCHAN means all channels.\n+ * @param[out] stats\n+ * The basic statistics structure encapsulated into rte_dmadev_stats\n+ * object.\n+ *\n+ * @return\n+ * - =0: Successfully retrieve stats.\n+ * - <0: Failure to retrieve stats.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_stats_get(uint16_t dev_id, uint16_t vchan,\n+\t\t struct rte_dmadev_stats *stats);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Reset basic statistics of a or all virtual DMA channel(s).\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * If equal RTE_DMADEV_ALL_VCHAN means all channels.\n+ *\n+ * @return\n+ * - =0: Successfully reset stats.\n+ * - <0: Failure to reset stats.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_stats_reset(uint16_t dev_id, uint16_t vchan);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Dump DMA device info.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param f\n+ * The file to write the output to.\n+ *\n+ * @return\n+ * 0 on success. Non-zero otherwise.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_dump(uint16_t dev_id, FILE *f);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Trigger the dmadev self test.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ *\n+ * @return\n+ * - 0: Selftest successful.\n+ * - -ENOTSUP if the device doesn't support selftest\n+ * - other values < 0 on failure.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_selftest(uint16_t dev_id);\n+\n+/**\n+ * rte_dma_status_code - DMA transfer result status code defines.\n+ */\n+enum rte_dma_status_code {\n+\tRTE_DMA_STATUS_SUCCESSFUL,\n+\t/**< The operation completed successfully. */\n+\tRTE_DMA_STATUS_USER_ABORT,\n+\t/**< The operation failed to complete due abort by user.\n+\t * This is mainly used when processing dev_stop, user could modidy the\n+\t * descriptors (e.g. change one bit to tell hardware abort this job),\n+\t * it allows outstanding requests to be complete as much as possible,\n+\t * so reduce the time to stop the device.\n+\t */\n+\tRTE_DMA_STATUS_NOT_ATTEMPTED,\n+\t/**< The operation failed to complete due to following scenarios:\n+\t * The jobs in a particular batch are not attempted because they\n+\t * appeared after a fence where a previous job failed. In some HW\n+\t * implementation it's possible for jobs from later batches would be\n+\t * completed, though, so report the status from the not attempted jobs\n+\t * before reporting those newer completed jobs.\n+\t */\n+\tRTE_DMA_STATUS_INVALID_SRC_ADDR,\n+\t/**< The operation failed to complete due invalid source address. */\n+\tRTE_DMA_STATUS_INVALID_DST_ADDR,\n+\t/**< The operation failed to complete due invalid destination\n+\t * address.\n+\t */\n+\tRTE_DMA_STATUS_INVALID_ADDR,\n+\t/**< The operation failed to complete due invalid source or destination\n+\t * address, cover the case that only knows the address error, but not\n+\t * sure which address error.\n+\t */\n+\tRTE_DMA_STATUS_INVALID_LENGTH,\n+\t/**< The operation failed to complete due invalid length. */\n+\tRTE_DMA_STATUS_INVALID_OPCODE,\n+\t/**< The operation failed to complete due invalid opcode.\n+\t * The DMA descriptor could have multiple format, which are\n+\t * distinguished by the opcode field.\n+\t */\n+\tRTE_DMA_STATUS_BUS_ERROR,\n+\t/**< The operation failed to complete due bus err. */\n+\tRTE_DMA_STATUS_DATA_POISION,\n+\t/**< The operation failed to complete due data poison. */\n+\tRTE_DMA_STATUS_DESCRIPTOR_READ_ERROR,\n+\t/**< The operation failed to complete due descriptor read error. */\n+\tRTE_DMA_STATUS_DEV_LINK_ERROR,\n+\t/**< The operation failed to complete due device link error.\n+\t * Used to indicates that the link error in the memory-to-device/\n+\t * device-to-memory/device-to-device transfer scenario.\n+\t */\n+\tRTE_DMA_STATUS_ERROR_UNKNOWN = 0x100,\n+\t/**< The operation failed to complete due unknown reason.\n+\t * The initial value is 256, which reserves space for future errors.\n+\t */\n+};\n+\n+/**\n+ * rte_dmadev_sge - can hold scatter-gather DMA operation request entry.\n+ */\n+struct rte_dmadev_sge {\n+\trte_iova_t addr; /**< The DMA operation address. */\n+\tuint32_t length; /**< The DMA operation length. */\n+};\n+\n+/* DMA flags to augment operation preparation. */\n+#define RTE_DMA_OP_FLAG_FENCE\t(1ull << 0)\n+/**< DMA fence flag.\n+ * It means the operation with this flag must be processed only after all\n+ * previous operations are completed.\n+ * If the specify DMA HW works in-order (it means it has default fence between\n+ * operations), this flag could be NOP.\n+ *\n+ * @see rte_dmadev_copy()\n+ * @see rte_dmadev_copy_sg()\n+ * @see rte_dmadev_fill()\n+ */\n+\n+#define RTE_DMA_OP_FLAG_SUBMIT\t(1ull << 1)\n+/**< DMA submit flag.\n+ * It means the operation with this flag must issue doorbell to hardware after\n+ * enqueued jobs.\n+ */\n+\n+#define RTE_DMA_OP_FLAG_LLC\t(1ull << 2)\n+/**< DMA write data to low level cache hint.\n+ * Used for performance optimization, this is just a hint, and there is no\n+ * capability bit for this, driver should not return error if this flag was set.\n+ */\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Enqueue a copy operation onto the virtual DMA channel.\n+ *\n+ * This queues up a copy operation to be performed by hardware, if the 'flags'\n+ * parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin\n+ * this operation, otherwise do not trigger doorbell.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * @param src\n+ * The address of the source buffer.\n+ * @param dst\n+ * The address of the destination buffer.\n+ * @param length\n+ * The length of the data to be copied.\n+ * @param flags\n+ * An flags for this operation.\n+ * @see RTE_DMA_OP_FLAG_*\n+ *\n+ * @return\n+ * - 0..UINT16_MAX: index of enqueued copy job.\n+ * - <0: Error code returned by the driver copy function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_copy(uint16_t dev_id, uint16_t vchan, rte_iova_t src, rte_iova_t dst,\n+\t\tuint32_t length, uint64_t flags);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Enqueue a scatter-gather list copy operation onto the virtual DMA channel.\n+ *\n+ * This queues up a scatter-gather list copy operation to be performed by\n+ * hardware, if the 'flags' parameter contains RTE_DMA_OP_FLAG_SUBMIT then\n+ * trigger doorbell to begin this operation, otherwise do not trigger doorbell.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * @param src\n+ * The pointer of source scatter-gather entry array.\n+ * @param dst\n+ * The pointer of destination scatter-gather entry array.\n+ * @param nb_src\n+ * The number of source scatter-gather entry.\n+ * @see struct rte_dmadev_info::max_sges\n+ * @param nb_dst\n+ * The number of destination scatter-gather entry.\n+ * @see struct rte_dmadev_info::max_sges\n+ * @param flags\n+ * An flags for this operation.\n+ * @see RTE_DMA_OP_FLAG_*\n+ *\n+ * @return\n+ * - 0..UINT16_MAX: index of enqueued copy scatter-gather list job.\n+ * - <0: Error code returned by the driver copy scatter-gather list function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_copy_sg(uint16_t dev_id, uint16_t vchan, struct rte_dmadev_sge *src,\n+\t\t struct rte_dmadev_sge *dst, uint16_t nb_src, uint16_t nb_dst,\n+\t\t uint64_t flags);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Enqueue a fill operation onto the virtual DMA channel.\n+ *\n+ * This queues up a fill operation to be performed by hardware, if the 'flags'\n+ * parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin\n+ * this operation, otherwise do not trigger doorbell.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * @param pattern\n+ * The pattern to populate the destination buffer with.\n+ * @param dst\n+ * The address of the destination buffer.\n+ * @param length\n+ * The length of the destination buffer.\n+ * @param flags\n+ * An flags for this operation.\n+ * @see RTE_DMA_OP_FLAG_*\n+ *\n+ * @return\n+ * - 0..UINT16_MAX: index of enqueued fill job.\n+ * - <0: Error code returned by the driver fill function.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_fill(uint16_t dev_id, uint16_t vchan, uint64_t pattern,\n+\t\trte_iova_t dst, uint32_t length, uint64_t flags);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Trigger hardware to begin performing enqueued operations.\n+ *\n+ * This API is used to write the \"doorbell\" to the hardware to trigger it\n+ * to begin the operations previously enqueued by rte_dmadev_copy/fill().\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ *\n+ * @return\n+ * - =0: Successfully trigger hardware.\n+ * - <0: Failure to trigger hardware.\n+ */\n+__rte_experimental\n+int\n+rte_dmadev_submit(uint16_t dev_id, uint16_t vchan);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Returns the number of operations that have been successfully completed.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * @param nb_cpls\n+ * The maximum number of completed operations that can be processed.\n+ * @param[out] last_idx\n+ * The last completed operation's index.\n+ * If not required, NULL can be passed in.\n+ * @param[out] has_error\n+ * Indicates if there are transfer error.\n+ * If not required, NULL can be passed in.\n+ *\n+ * @return\n+ * The number of operations that successfully completed. This return value\n+ * must be less than or equal to the value of nb_cpls.\n+ */\n+__rte_experimental\n+uint16_t\n+rte_dmadev_completed(uint16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,\n+\t\t uint16_t *last_idx, bool *has_error);\n+\n+/**\n+ * @warning\n+ * @b EXPERIMENTAL: this API may change without prior notice.\n+ *\n+ * Returns the number of operations that have been completed, and the\n+ * operations result may succeed or fail.\n+ *\n+ * @param dev_id\n+ * The identifier of the device.\n+ * @param vchan\n+ * The identifier of virtual DMA channel.\n+ * @param nb_cpls\n+ * Indicates the size of status array.\n+ * @param[out] last_idx\n+ * The last completed operation's index.\n+ * If not required, NULL can be passed in.\n+ * @param[out] status\n+ * This is a pointer to an array of length 'nb_cpls' that holds the completion\n+ * status code of each operation.\n+ * @see enum rte_dma_status_code\n+ *\n+ * @return\n+ * The number of operations that completed. This return value must be less\n+ * than or equal to the value of nb_cpls.\n+ * If this number is greater than zero (assuming n), then n values in the\n+ * status array are also set.\n+ */\n+__rte_experimental\n+uint16_t\n+rte_dmadev_completed_status(uint16_t dev_id, uint16_t vchan,\n+\t\t\t const uint16_t nb_cpls, uint16_t *last_idx,\n+\t\t\t enum rte_dma_status_code *status);\n+\n+#ifdef __cplusplus\n+}\n+#endif\n+\n+#endif /* _RTE_DMADEV_H_ */\ndiff --git a/lib/dmadev/version.map b/lib/dmadev/version.map\nnew file mode 100644\nindex 0000000..02fffe3\n--- /dev/null\n+++ b/lib/dmadev/version.map\n@@ -0,0 +1,25 @@\n+EXPERIMENTAL {\n+\tglobal:\n+\n+\trte_dmadev_close;\n+\trte_dmadev_completed;\n+\trte_dmadev_completed_status;\n+\trte_dmadev_configure;\n+\trte_dmadev_copy;\n+\trte_dmadev_copy_sg;\n+\trte_dmadev_count;\n+\trte_dmadev_dump;\n+\trte_dmadev_fill;\n+\trte_dmadev_get_dev_id;\n+\trte_dmadev_info_get;\n+\trte_dmadev_is_valid_dev;\n+\trte_dmadev_selftest;\n+\trte_dmadev_start;\n+\trte_dmadev_stats_get;\n+\trte_dmadev_stats_reset;\n+\trte_dmadev_stop;\n+\trte_dmadev_submit;\n+\trte_dmadev_vchan_setup;\n+\n+\tlocal: *;\n+};\ndiff --git a/lib/meson.build b/lib/meson.build\nindex 1673ca4..a542c23 100644\n--- a/lib/meson.build\n+++ b/lib/meson.build\n@@ -44,6 +44,7 @@ libraries = [\n 'power',\n 'pdump',\n 'rawdev',\n+ 'dmadev',\n 'regexdev',\n 'rib',\n 'reorder',\n", "prefixes": [ "v13", "1/6" ] }